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

outerloop/housekeeping.py

@@ -0,0 +1,167 @@
+"""Disk housekeeping: ended runs shed their workspaces.
+
+A run's workspace (`ws/`, the clone the session worked in, and `ws-home/`,
+the session's home with its tool caches) is the bulk of what a run leaves
+on the state filesystem, in files far more than in bytes: 2026-09-03 the
+scratch quota on Torch hit its 5M-file ceiling with 1.67M of them under
+state/runs, and no tick could start for two hours. Everything the record
+keeps for the research record lives outside those two directories: the
+run's state.json, its report, its transcripts, and the ledger entries; the
+tree itself is on GitHub (the PR branch, or the research line's snapshot).
+
+Rules (docs/design/disk-maintenance.md):
+
+- only ENDED runs shed, and only the two directories `ws` and `ws-home`;
+- after a grace period (default 24 h, for post-mortems), oldest first;
+- when the state filesystem's write probe FAILS, the grace is waived: the
+  tick sheds until the probe passes again, so a full quota heals itself;
+- a workspace whose top-level entry is a symlink is not removed (a session
+  could aim it anywhere); it is logged and left for a human;
+- the record notes when it shed (`workspace_shed`), so nothing runs twice.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import time
+from dataclasses import replace
+from pathlib import Path
+
+from outerloop.runstate import ENDED, RunRecord, list_runs, load_record, run_dir, save_record
+
+log = logging.getLogger(__name__)
+
+WORKSPACE_DIRS = ("ws", "ws-home")
+DEFAULT_SHED_GRACE_S = 24 * 3600.0
+
+
+def shed_candidates(root: Path, now: float, grace_s: float, force: bool) -> list[RunRecord]:
+    """Ended runs whose workspaces may go now, oldest ending first. With
+    `force` (the disk is failing) the grace period does not apply."""
+    due: list[RunRecord] = []
+    for record in list_runs(root):
+        if record.state != ENDED or record.workspace_shed:
+            continue
+        if not force and now - record.updated < grace_s:
+            continue
+        if not any((run_dir(root, record.run_id) / d).exists() for d in WORKSPACE_DIRS):
+            continue
+        due.append(record)
+    due.sort(key=lambda r: r.updated)
+    return due
+
+
+def shed_workspace(root: Path, record: RunRecord, now: float) -> bool:
+    """Remove the run's `ws` and `ws-home` directories and stamp the record.
+    Returns False (and removes nothing) when either is a symlink."""
+    base = run_dir(root, record.run_id)
+    targets = [base / d for d in WORKSPACE_DIRS if (base / d).exists() or (base / d).is_symlink()]
+    for path in targets:
+        if path.is_symlink():
+            log.warning("not shedding %s: %s is a symlink", record.run_id, path.name)
+            return False
+    for path in targets:
+        shutil.rmtree(path, ignore_errors=True)
+    remaining = [p.name for p in targets if p.exists()]
+    if remaining:
+        log.warning("shed %s incompletely: %s remain", record.run_id, ", ".join(remaining))
+        return False
+    save_record(root, replace(record, workspace_shed=now), now)
+    return True
+
+
+_TS_RE = re.compile(r"(\d{8}-\d{6})")
+
+
+def _run_id_timestamp(run_id: str) -> str | None:
+    m = _TS_RE.search(run_id)
+    return m.group(1) if m else None
+
+
+def _is_shed_candidate(
+    root: Path, record: RunRecord, now: float, grace_s: float, force: bool
+) -> bool:
+    if record.state != ENDED or record.workspace_shed:
+        return False
+    if not force and now - record.updated < grace_s:
+        return False
+    return any((run_dir(root, record.run_id) / d).exists() for d in WORKSPACE_DIRS)
+
+
+def shed_ended_workspaces(
+    root: Path,
+    now: float,
+    *,
+    grace_s: float = DEFAULT_SHED_GRACE_S,
+    force: bool = False,
+    limit: int = 3,
+    time_budget_s: float = 120.0,
+    until_ok: object = None,
+    clock: object = None,
+) -> list[str]:
+    """Shed due workspaces until `limit` is reached or `time_budget_s`
+    elapses, checking the budget between runs; a forced sweep also stops when
+    `until_ok` reports a healthy disk.
+
+    Bounded by BOTH a count (`limit`) and a wall-clock budget
+    (`time_budget_s`). Removing a workspace is `rm -rf` over the state
+    filesystem, tens of thousands of tiny files each on a networked FS, so an
+    unbounded batch inside a tick can run for many minutes and blow the tick's
+    own timeout (2026-09-03: a 50-run batch, and reading every record to find
+    candidates, killed the tick before it could publish). Discovery is ONE
+    directory read, sorted oldest-first by the timestamp embedded in each run
+    id (no per-entry stat, no record load); the loop then loads one record at
+    a time and checks the budget EACH step, so both are bounded. The backlog
+    drains over several ticks. With `until_ok` a forced sweep also stops as
+    soon as the disk reports healthy."""
+    monotonic = clock if callable(clock) else time.monotonic
+    start = monotonic()
+    runs_root = root / "runs"
+    try:
+        # ONE directory read (no per-entry stat), sorted oldest-first by the
+        # timestamp every run id carries (`<name>-YYYYMMDD-HHMMSS-...`), which
+        # is chronological across benchmark prefixes where a lexical sort is
+        # not; ids without one sort last so they never block the backlog.
+        run_ids = sorted(
+            (e.name for e in os.scandir(runs_root)),
+            key=lambda name: (_run_id_timestamp(name) or "99999999-999999", name),
+        )
+    except OSError:
+        return []
+    # One readdir + an in-memory sort is cheap even for thousands of run dirs,
+    # but never start shedding if it somehow overran the budget: the tick then
+    # spends the rest of its time publishing, not deleting.
+    if monotonic() - start >= time_budget_s:
+        return []
+    shed: list[str] = []
+    for run_id in run_ids:
+        if len(shed) >= limit:
+            break
+        if monotonic() - start >= time_budget_s:
+            log.info(
+                "housekeeping: time budget (%.0fs) reached; %d shed this tick",
+                time_budget_s,
+                len(shed),
+            )
+            break
+        if until_ok is not None and callable(until_ok) and until_ok():
+            break
+        try:
+            record = load_record(root, run_id)
+        except (OSError, ValueError, TypeError, KeyError):
+            continue
+        if _is_shed_candidate(root, record, now, grace_s, force) and shed_workspace(
+            root, record, now
+        ):
+            shed.append(run_id)
+    if shed:
+        log.info(
+            "shed %d ended workspace(s)%s: %s",
+            len(shed),
+            " (forced)" if force else "",
+            ", ".join(shed),
+        )
+    return shed

outerloop/init.py

@@ -0,0 +1,313 @@
+"""`outerloop init` — the guided setup.
+
+Collects placement (Slurm or local), the target repo, and bot auth, then writes
+`~/.config/outerloop/.env` (plus the credential files), so a new adopter never
+hand-edits config or reasons about which `OUTERLOOP_*` keys to set. Flags fill
+answers non-interactively; anything left out is prompted for (a secret via
+getpass, never echoed). Auth is the adopter's own GitHub App by default —
+`--github-app`, one click via the manifest flow in `appmanifest.py` — with a PAT
+as the fallback; either way `resolve_bot_auth` reads the result exactly as
+`outerloop start` does. An existing `.env` is never overwritten without asking.
+
+The config location is `cli.ENV_FILE`, the same file `start` reads — one source
+of truth, so a rename of the config dir moves both together.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from outerloop.cli import ENV_FILE
+
+CONFIG_DIR = ENV_FILE.parent
+DEFAULT_PAT_FILE = CONFIG_DIR / "bot_pat"
+API = "https://api.github.com"
+# The climbing author's harnesses (attempt.py's --author-backend choices).
+AUTHOR_BACKENDS = ("claude", "codex")
+
+
+@dataclass
+class InitAnswers:
+    compute: str  # "slurm" | "local"
+    target: str  # "owner/repo"
+    root: str = ""  # Slurm state root on the shared filesystem
+    account: str = ""  # Slurm account (required for Slurm)
+    partition: str = ""  # Slurm partition (optional; unset -> Slurm default)
+    author_backend: str = ""  # optional: the climbing author's harness
+    author_model: str = ""  # optional
+
+
+def render_env(a: InitAnswers, pat_file: str = "", *, app_file: str = "") -> str:
+    """The `.env` body for these answers — only the keys that have a value, so
+    the file stays minimal and every line means something. Ordered placement →
+    target → auth → author to read top-to-bottom like the setup itself. Auth is
+    an App file (`--github-app`) or a PAT file, never both."""
+    lines = [f"OUTERLOOP_COMPUTE={a.compute}"]
+    if a.compute == "slurm":
+        lines.append(f"OUTERLOOP_ROOT={a.root}")
+        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}")
+    lines.append(f"OUTERLOOP_TARGET={a.target}")
+    if app_file:
+        lines.append(f"OUTERLOOP_GITHUB_APP_FILE={app_file}")
+    elif pat_file:
+        lines.append(f"OUTERLOOP_PAT_FILE={pat_file}")
+    if a.author_backend:
+        lines.append(f"OUTERLOOP_AUTHOR_BACKEND={a.author_backend}")
+    if a.author_model:
+        lines.append(f"OUTERLOOP_AUTHOR_MODEL={a.author_model}")
+    return "\n".join(lines) + "\n"
+
+
+def write_config(
+    a: InitAnswers, token: str, pat_file: str, *, config_dir: Path = CONFIG_DIR
+) -> tuple[Path, Path | None]:
+    """Write the PAT file (only when a token is pasted) and the `.env`, both
+    owner-only (0600) — `start`/`tick_deploy` refuse a group/world-readable
+    `.env`, and a token file must never be wider. Returns (env_path, pat_path)."""
+    config_dir.mkdir(parents=True, exist_ok=True)
+    written_pat: Path | None = None
+    if token:
+        pat_path = config_dir / DEFAULT_PAT_FILE.name
+        # printf-style: no trailing newline — the deploy `cat`s this file into
+        # the git credential, and a trailing newline rides along and breaks auth.
+        pat_path.write_text(token)
+        pat_path.chmod(0o600)
+        written_pat = pat_path
+        pat_file = str(pat_path)
+    env_path = config_dir / ENV_FILE.name
+    env_path.write_text(render_env(a, pat_file))
+    env_path.chmod(0o600)
+    return env_path, written_pat
+
+
+def _check_repo_access(token: str, target: str) -> str:
+    """Can this token write the target repo? "" on success, else a short reason.
+    Never raises — a check failure is a warning, not a reason to abandon config."""
+    req = urllib.request.Request(
+        f"{API}/repos/{target}",
+        headers={"Authorization": f"token {token}", "Accept": "application/vnd.github+json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            body = json.loads(resp.read())
+        perms = body.get("permissions") or {}
+        if not perms.get("push"):
+            return f"reaches {target} but lacks write access (it opens PRs)"
+        return ""
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return f"{target} not found, or the token cannot see it"
+        return f"GitHub returned {exc.code} for {target}"
+    except urllib.error.URLError as exc:
+        return f"could not reach GitHub: {exc.reason}"
+
+
+def validate_pat(pat_file: str, target: str) -> str:
+    """Best-effort: can the PAT in `pat_file` write the target repo?"""
+    try:
+        token = Path(pat_file).expanduser().read_text().strip()
+    except OSError as exc:
+        return f"could not read {pat_file}: {exc}"
+    if not token:
+        return f"{pat_file} is empty"
+    return _check_repo_access(token, target)
+
+
+def _ask(prompt: str, default: str = "", *, required: bool = False) -> str:
+    """One interactive prompt with an optional default; re-asks while a required
+    answer is blank."""
+    suffix = f" [{default}]" if default else ""
+    while True:
+        got = input(f"{prompt}{suffix}: ").strip() or default
+        if got or not required:
+            return got
+        print("  (required)")
+
+
+def _collect(args: argparse.Namespace, interactive: bool) -> tuple[InitAnswers, str]:
+    """Merge flags with prompts (when interactive) into answers + a PAT-file
+    path. `args.pat_file` names an existing file; otherwise, interactively, a
+    pasted token is returned separately to be written 0600."""
+    compute = args.compute or (_ask("Compute: slurm or local", "slurm") if interactive else "slurm")
+    compute = compute.lower()
+    target = args.target or (_ask("Target repo (owner/repo)", required=True) if interactive else "")
+    root = account = partition = ""
+    if compute == "slurm":
+        root = args.root or (
+            _ask("Slurm state root (shared filesystem)", required=True) if interactive else ""
+        )
+        account = args.account or (_ask("Slurm account", required=True) if interactive else "")
+        partition = args.partition or (
+            _ask("Slurm partition (blank = Slurm default; a,b for a list)") if interactive else ""
+        )
+    # Author config is part of the full setup, not the focused --github-app run
+    # (that one is about auth). When asked, offer the fixed set, not a blank.
+    ask_author = interactive and not args.github_app
+    backend = args.author_backend or (
+        _ask("Author backend (claude or codex)", "claude") if ask_author else ""
+    )
+    model = args.author_model or (
+        _ask("Author model (blank = the backend's default)") if ask_author else ""
+    )
+    answers = InitAnswers(
+        compute=compute,
+        target=target,
+        root=root,
+        account=account,
+        partition=partition,
+        author_backend=backend,
+        author_model=model,
+    )
+    return answers, (args.pat_file or "")
+
+
+def _github_app_setup(answers: InitAnswers, app_name: str, org: str) -> int:
+    """The `--github-app` path: create the adopter's own App via the manifest
+    flow, write its creds, help install it, then point the .env at the App file.
+    Interactive by nature (a browser click + install), so no `--yes` variant."""
+    from outerloop import appmanifest
+
+    owner = org or answers.target.split("/")[0]
+    name = app_name or f"outerloop-{owner}"[:34]  # GitHub caps App names at 34
+    code = appmanifest.request_manifest_code(
+        name, "https://github.com/outerloop-science/outerloop", org
+    )
+    if not code:
+        print("outerloop init: no code entered — nothing created", file=sys.stderr)
+        return 1
+    try:
+        conversion = appmanifest.convert_manifest(code)
+    except ValueError as exc:
+        print(f"outerloop init: {exc}", file=sys.stderr)
+        return 1
+    pem_path, app_json = appmanifest.save_app_creds(conversion, CONFIG_DIR)
+    print(f"created App '{conversion['slug']}' — wrote {app_json} and {pem_path} (0600)")
+    print(f"install it on {answers.target}: {appmanifest.install_url(conversion)}")
+    input("press Enter once you've installed the App… ")
+    iid = appmanifest.capture_installation_id(int(conversion["id"]), pem_path, owner)
+    if iid:
+        appmanifest.set_installation_id(app_json, iid)
+        print(f"  installation id {iid} recorded")
+        # Self-verify end to end: mint a real installation token and check it can
+        # write the target — this is what confirms the whole flow actually worked.
+        from outerloop.appauth import app_provider_from_file
+
+        try:
+            token = app_provider_from_file(app_json).token()
+            problem = _check_repo_access(token, answers.target)
+            print(f"  auth check: {'ok' if not problem else 'WARNING — ' + problem}")
+        except Exception as exc:  # a check failure is a warning, never fails setup
+            print(f"  auth check: WARNING — could not mint a token: {exc}")
+    else:
+        print(
+            f"  no installation found yet — install the App, then set installation_id in {app_json}"
+        )
+    env_path = CONFIG_DIR / ENV_FILE.name
+    env_path.write_text(render_env(answers, app_file=str(app_json)))
+    env_path.chmod(0o600)
+    print(f"wrote {env_path}")
+    print("next: outerloop start")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="outerloop init", description="guided setup for outerloop"
+    )
+    parser.add_argument("--compute", choices=["slurm", "local"], help="where the loop runs")
+    parser.add_argument("--target", help="the repo the agents work on, owner/repo")
+    parser.add_argument("--root", help="Slurm state root on the shared filesystem")
+    parser.add_argument("--account", help="Slurm account")
+    parser.add_argument(
+        "--partition", help="Slurm partition (optional; blank = default; a,b = list)"
+    )
+    parser.add_argument(
+        "--pat-file", dest="pat_file", help="path to an existing file holding a PAT"
+    )
+    parser.add_argument(
+        "--github-app",
+        dest="github_app",
+        action="store_true",
+        help="create your own GitHub App in a browser (one click) instead of a PAT",
+    )
+    parser.add_argument("--app-name", dest="app_name", help="name for the created GitHub App")
+    parser.add_argument("--org", help="create the App under this org (default: your account)")
+    parser.add_argument("--author-backend", dest="author_backend", help="climbing author's backend")
+    parser.add_argument("--author-model", dest="author_model", help="climbing author's model")
+    parser.add_argument(
+        "--yes", "-y", action="store_true", help="non-interactive: use flags, do not prompt"
+    )
+    parser.add_argument(
+        "--force", action="store_true", help="overwrite an existing config without asking"
+    )
+    args = parser.parse_args(sys.argv[2:] if argv is None else argv)
+    interactive = not args.yes
+
+    answers, pat_file = _collect(args, interactive)
+    if not answers.target:
+        print("outerloop init: a target repo is required (--target owner/repo)", file=sys.stderr)
+        return 2
+    if answers.compute == "slurm" and not (answers.root and answers.account):
+        print("outerloop init: Slurm needs --root and --account", file=sys.stderr)
+        return 2
+    if answers.author_backend and answers.author_backend not in AUTHOR_BACKENDS:
+        print(
+            f"outerloop init: author backend must be one of {', '.join(AUTHOR_BACKENDS)}",
+            file=sys.stderr,
+        )
+        return 2
+
+    # Never clobber a working setup silently: a re-run of init on a configured
+    # machine must ask (or be told --force). Checked before any App is created.
+    env_path = CONFIG_DIR / ENV_FILE.name
+    if env_path.exists() and not args.force:
+        if not interactive:
+            print(f"outerloop init: {env_path} exists; pass --force to overwrite", file=sys.stderr)
+            return 1
+        if not _ask(f"{env_path} exists — overwrite it? (y/N)", "n").lower().startswith("y"):
+            print(
+                "outerloop init: kept the existing config (--force skips this check)",
+                file=sys.stderr,
+            )
+            return 1
+
+    # The App is the recommended credential (scoped, revocable, no plaintext
+    # token); the PAT is the fallback. Offer it first when interactive.
+    if not args.github_app and not pat_file and interactive:
+        choice = _ask(
+            "Auth — [app] create your own GitHub App (recommended) or [pat] paste a token",
+            "app",
+        ).lower()
+        if choice.startswith("a"):
+            args.github_app = True
+    if args.github_app:
+        return _github_app_setup(answers, args.app_name or "", args.org or "")
+
+    token = ""
+    if not pat_file and interactive:
+        # re-collect only the token here so _collect stays pure of getpass in tests
+        token = getpass.getpass(
+            "Paste a GitHub PAT with write access to the target (hidden; blank to skip): "
+        ).strip()
+
+    env_path, pat_path = write_config(answers, token, pat_file, config_dir=CONFIG_DIR)
+    print(f"wrote {env_path}")
+    if pat_path:
+        print(f"wrote {pat_path} (0600)")
+    effective_pat = str(pat_path) if pat_path else pat_file
+    if effective_pat:
+        problem = validate_pat(effective_pat, answers.target)
+        print(f"  auth check: {'ok' if not problem else 'WARNING — ' + problem}")
+    else:
+        print("  no PAT set — add OUTERLOOP_PAT_FILE before the agents can open PRs")
+    print("next: outerloop start")
+    return 0

outerloop/intake.py

@@ -0,0 +1,129 @@
+"""The requested lane: maintainer issues become runs.
+
+An open issue on the target repo qualifies when its author carries repo
+standing (same association gate as review comments). The tick claims at most
+one per cycle by commenting a claim marker, then submits a climb job whose
+task carries the issue text data-fenced; the resulting PR references the
+issue, and the run's report lands back on the issue thread — the loop closes
+with whoever asked (docs/design/architecture.md, "The life of a run").
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+from outerloop.brief import MAX_TASK_CHARS, _cap, _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
+
+log = logging.getLogger(__name__)
+
+CLAIM_MARKER = marker("claimed")
+# Posted (by the bot only) to undo a claim whose run never started — a failed
+# submit must not strand the issue, since the claim scan skips claimed issues.
+RELEASE_MARKER = marker("claim-released")
+# Claim attempts per issue before intake gives up on it: a durable submit
+# 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)
+class IssueTask:
+    number: int
+    title: str
+    body: str
+    author: str
+    benchmark: str  # inferred from the issue text against the contract
+
+
+def infer_benchmark(text: str, contract: Contract) -> str:
+    """The single contract benchmark the issue names, or "" if not exactly
+    one — ambiguity is a human problem, not a guess."""
+    lowered = text.casefold()
+    named = [b.name for b in contract.benchmarks if b.name.casefold() in lowered]
+    return named[0] if len(named) == 1 else ""
+
+
+def qualifying_issue(issue: dict, bot_login: str) -> bool:
+    author = str((issue.get("user") or {}).get("login", ""))
+    if is_own_login(author, bot_login):
+        return False  # the kernel's own issues (research log, alarms) are never orders
+    if str(issue.get("author_association", "")) not in QUALIFYING_ASSOCIATIONS:
+        return False
+    return bool(str(issue.get("title") or "").strip())
+
+
+def pick_issue(github, repo: str, contract: Contract, bot_login: str) -> IssueTask | None:
+    """The oldest qualifying, unclaimed issue that names exactly one
+    benchmark. At most one — intake is deliberately slow."""
+    if not bot_login.strip():
+        # fail closed like the steward picker: with no identity the claim
+        # scan below would see NO claims and re-claim every tick — an
+        # unbounded paid loop
+        log.warning("pick_issue: bot_login is blank; intake lane sits out")
+        return None
+    issues = sorted(github.list_open_issues(repo), key=lambda i: i.get("number", 0))
+    for issue in issues:
+        labels = {
+            str(label.get("name", "")).casefold()
+            for label in issue.get("labels", [])
+            if isinstance(label, dict)
+        }
+        if has_label(labels, "steward"):
+            continue  # the steward lane's, never the solver's
+        if not qualifying_issue(issue, bot_login):
+            continue
+        number = int(issue["number"])
+        claimed = False
+        attempts = 0
+        for c in github.list_comments(repo, number):
+            author = str((c.get("user") or {}).get("login", ""))
+            if not is_own_login(author, bot_login):
+                continue  # only the bot's own markers count — no forged releases
+            body = str(c.get("body", ""))
+            if has_marker(body, "claimed"):
+                claimed = True
+                attempts += 1
+            if has_marker(body, "claim-released"):
+                claimed = False
+        if claimed:
+            continue  # already claimed by a run
+        if attempts >= MAX_INTAKE_ATTEMPTS:
+            log.info("issue #%s burned %d claim attempts; needs a human look", number, attempts)
+            continue
+        text = f"{issue.get('title', '')}\n{issue.get('body') or ''}"
+        benchmark = infer_benchmark(text, contract)
+        if not benchmark:
+            log.info("issue #%s names zero or several benchmarks; skipping", number)
+            continue
+        return IssueTask(
+            number=number,
+            title=str(issue.get("title") or ""),
+            body=str(issue.get("body") or ""),
+            author=str((issue.get("user") or {}).get("login", "")),
+            benchmark=benchmark,
+        )
+    return None
+
+
+def issue_hypothesis(task: IssueTask) -> str:
+    """The task text for the brief: the maintainer's ask, data-fenced.
+
+    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)
+    return (
+        f"A maintainer (@{task.author}) opened issue #{task.number} requesting "
+        f"work on the `{task.benchmark}` benchmark. Their request:\n"
+        f"{fence}\n{quoted}\n{fence}\n"
+        "Address the request's substance within the contract's rules."
+    )