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

outerloop/cli.py

@@ -2,7 +2,7 @@
 
 With `sbatch` on PATH it submits the resident tick
 (docs/design/resident-tick.md) and returns; without it, or with
-AUTORESEARCH_COMPUTE=local, it runs the local loop in the foreground.
+OUTERLOOP_COMPUTE=local, it runs the local loop in the foreground.
 Settings come from flags, then the process environment, then
 ~/.config/outerloop/.env, read once here at launch. The running chain
 never takes identity or placement from that file (tick_deploy.sh reads an
@@ -18,49 +18,59 @@ import shutil
 import stat
 import subprocess
 import sys
+from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
 
 from outerloop import paths
 
-RESIDENT_JOB_NAME = "autoresearch-resident"
+RESIDENT_JOB_NAME = "outerloop-resident"
+# A resident submitted before the rename. Slurm's singleton serializes jobs by
+# NAME, so `start` must refuse while one of these is queued or running (two
+# residents on one root is what the singleton prevents). Dropped in the
+# release after 0.1.
+LEGACY_RESIDENT_JOB_NAME = "autoresearch-resident"
 DEFAULT_RESIDENT_MINUTES = 360  # cpu_short's ceiling on Torch; the loop hands over to itself
-DEFAULT_LOCAL_ROOT = Path.home() / ".autoresearch"
+DEFAULT_LOCAL_ROOT = Path.home() / ".outerloop"
+LEGACY_LOCAL_ROOT_NAME = ".autoresearch"  # pre-rename; honored until the release after 0.1
 ENV_FILE = paths.ENV_FILE  # ~/.config/outerloop/.env, or the pre-rename dir (see paths.py)
 
 # What start itself decides from: mode, placement, root, cadence, walltime.
 START_KEYS = (
-    "AUTORESEARCH_COMPUTE",
-    "AUTORESEARCH_ROOT",
-    "AUTORESEARCH_ACCOUNT",
-    "AUTORESEARCH_PARTITION",
-    "AUTORESEARCH_CADENCE_MIN",
-    "AUTORESEARCH_RESIDENT_MINUTES",
-    "AUTORESEARCH_PAT_FILE",
+    "OUTERLOOP_COMPUTE",
+    "OUTERLOOP_ROOT",
+    "OUTERLOOP_ACCOUNT",
+    "OUTERLOOP_PARTITION",
+    "OUTERLOOP_CADENCE_MIN",
+    "OUTERLOOP_RESIDENT_MINUTES",
+    "OUTERLOOP_PAT_FILE",
 )
 # The author knobs the chain's deploy step exports from .env every tick. The
 # local loop has no deploy step, so start exports them once at launch; a test
 # keeps this list identical to tick_deploy.sh's.
 TICK_ENV_KEYS = (
-    "AUTORESEARCH_AUTHOR_BACKEND",
-    "AUTORESEARCH_AUTHOR_MODEL",
-    "AUTORESEARCH_CODEX_BIN",
-    "AUTORESEARCH_CODEX_KEY_FILE",
-    "AUTORESEARCH_CLAUDE_KEY_FILE",
-    "AUTORESEARCH_HARNESS_KEY_FILE",
-    "AUTORESEARCH_VERTEX_PROJECT",
-    "AUTORESEARCH_VERTEX_REGION",
-    "AUTORESEARCH_VERTEX_ADC",
-    "AUTORESEARCH_TARGET",
-    "AUTORESEARCH_GITHUB_APP_FILE",
-    "AUTORESEARCH_BOT_LOGIN",
-    "AUTORESEARCH_BOT_ALIASES",
-    "AUTORESEARCH_GPU_PARTITION",
-    "AUTORESEARCH_GPU_ACCOUNT",
-    "AUTORESEARCH_PANEL",
-    "AUTORESEARCH_PANEL_KEY_FILE",
-    "AUTORESEARCH_PANEL_CODEX_KEY_FILE",
-    "AUTORESEARCH_PANEL_HERMES_KEY_FILE",
+    "OUTERLOOP_AUTHOR_BACKEND",
+    "OUTERLOOP_AUTHOR_MODEL",
+    "OUTERLOOP_CLAUDE_BIN",
+    "OUTERLOOP_CODEX_BIN",
+    "OUTERLOOP_CODEX_KEY_FILE",
+    "OUTERLOOP_CLAUDE_KEY_FILE",
+    "OUTERLOOP_HARNESS_KEY_FILE",
+    "OUTERLOOP_VERTEX_PROJECT",
+    "OUTERLOOP_VERTEX_REGION",
+    "OUTERLOOP_VERTEX_ADC",
+    "OUTERLOOP_TARGET",
+    "OUTERLOOP_GITHUB_APP_FILE",
+    "OUTERLOOP_BOT_LOGIN",
+    "OUTERLOOP_BOT_ALIASES",
+    "OUTERLOOP_GPU_PARTITION",
+    "OUTERLOOP_GPU_ACCOUNT",
+    "OUTERLOOP_MAX_LAUNCH_GPUS",
+    "OUTERLOOP_IMAGE",
+    "OUTERLOOP_PANEL",
+    "OUTERLOOP_PANEL_KEY_FILE",
+    "OUTERLOOP_PANEL_CODEX_KEY_FILE",
+    "OUTERLOOP_PANEL_HERMES_KEY_FILE",
     "REVIEW_HERMES_REPO",
     "REVIEW_HERMES_PROVIDER",
 )
@@ -89,20 +99,26 @@ def env_file_values(path: Path = ENV_FILE, keys: tuple[str, ...] = START_KEYS) -
     except OSError as e:
         raise StartError(f"cannot read {path}: {e}") from None
     out: dict[str, str] = {}
+    canonical: set[str] = set()  # keys set by their OUTERLOOP_ spelling
     for raw in text.splitlines():
         line = raw.rstrip("\r").strip()
         if not line or line.startswith("#") or "=" not in line:
             continue
         key, value = line.split("=", 1)
         key = key.strip()
-        if key.startswith("OUTERLOOP_"):  # the public name; `keys` are canonical
-            key = "AUTORESEARCH_" + key[len("OUTERLOOP_") :]
+        legacy = key.startswith("AUTORESEARCH_")  # the pre-rename name, one more release
+        if legacy:
+            key = "OUTERLOOP_" + key[len("AUTORESEARCH_") :]
         if key not in keys:
             continue
+        if legacy and key in canonical:
+            continue  # the OUTERLOOP_ spelling wins whatever the file order
         value = value.strip()
         if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
             value = value[1:-1]
         out[key] = value
+        if not legacy:
+            canonical.add(key)
     return out
 
 
@@ -124,18 +140,19 @@ class StartPlan:
         reads as "whichever frees up first") without corrupting the export
         delimiter. start() merges these into the environment it hands sbatch."""
         env = {
-            "AUTORESEARCH_RESIDENT": "1",
-            "AUTORESEARCH_HOME": str(self.home),
-            "AUTORESEARCH_ROOT": str(self.root),
-            "AUTORESEARCH_ACCOUNT": self.account,
-            "AUTORESEARCH_RESIDENT_MINUTES": str(self.resident_minutes),  # successors reuse it
+            "OUTERLOOP_RESIDENT": "1",
+            "OUTERLOOP_HOME": str(self.home),
+            "OUTERLOOP_ROOT": str(self.root),
+            "OUTERLOOP_RESIDENT_MINUTES": str(self.resident_minutes),  # successors reuse it
         }
+        if self.account:
+            env["OUTERLOOP_ACCOUNT"] = self.account
         if self.partition:
-            env["AUTORESEARCH_PARTITION"] = self.partition
+            env["OUTERLOOP_PARTITION"] = self.partition
         if self.cadence_min:
-            env["AUTORESEARCH_CADENCE_MIN"] = self.cadence_min
+            env["OUTERLOOP_CADENCE_MIN"] = self.cadence_min
         if self.pat_file:
-            env["AUTORESEARCH_PAT_FILE"] = self.pat_file
+            env["OUTERLOOP_PAT_FILE"] = self.pat_file
         return env
 
     def command(self) -> list[str]:
@@ -147,8 +164,9 @@ class StartPlan:
             "--dependency=singleton",  # two starts can both submit; only one ever runs
             f"--time={self.resident_minutes}",
             f"--job-name={RESIDENT_JOB_NAME}",
-            f"--account={self.account}",
         ]
+        if self.account:  # unset bills the caller's default Slurm association
+            argv.append(f"--account={self.account}")
         if self.partition:  # unset lets Slurm choose its default partition
             argv.append(f"--partition={self.partition}")
         # --export=ALL carries export_env() from the inherited environment; a
@@ -168,7 +186,7 @@ def _setting(key: str, flag: str, environ: dict[str, str], from_file: dict[str,
 
 def _home(environ: dict[str, str], cwd: Path, *, local: bool, root: Path) -> Path:
     """The directory the loop runs from. On Slurm it must be a source
-    checkout (AUTORESEARCH_HOME, else the current directory): the chain
+    checkout (OUTERLOOP_HOME, else the current directory): the chain
     deploys from it and every job runs from a flight snapshot of its HEAD.
     The local loop has no deploy step and runs the installed package, so it
     uses a checkout when one is at hand and otherwise a `home` directory
@@ -196,10 +214,10 @@ def plan_start(
     sbatch_on_path: bool,
     cwd: Path,
 ) -> StartPlan:
-    compute = _setting("AUTORESEARCH_COMPUTE", "local" if local else "", environ, from_file)
+    compute = _setting("OUTERLOOP_COMPUTE", "local" if local else "", environ, from_file)
     mode = "local" if compute.strip().lower() == "local" or not sbatch_on_path else "slurm"
-    root_s = _setting("AUTORESEARCH_ROOT", root, environ, from_file)
-    cadence = _setting("AUTORESEARCH_CADENCE_MIN", "", environ, from_file)
+    root_s = _setting("OUTERLOOP_ROOT", root, environ, from_file)
+    cadence = _setting("OUTERLOOP_CADENCE_MIN", "", environ, from_file)
     if cadence:
         # the chain divides by it and the loop sleeps on it: a bad value would
         # only surface after the job started
@@ -209,13 +227,13 @@ def plan_start(
             cadence_ok = False
         if not cadence_ok:
             raise StartError(
-                f"AUTORESEARCH_CADENCE_MIN must be a positive number of minutes, got {cadence!r}"
+                f"OUTERLOOP_CADENCE_MIN must be a positive number of minutes, got {cadence!r}"
             )
-    pat = _setting("AUTORESEARCH_PAT_FILE", "", environ, from_file)
+    pat = _setting("OUTERLOOP_PAT_FILE", "", environ, from_file)
     # Slurm runs from a checkout; the local loop runs the installed package
     # and needs only a directory (the launch lanes and GitHub servicing
-    # switch off without AUTORESEARCH_HOME, so one is always set)
-    local_root = Path(root_s).expanduser() if root_s else DEFAULT_LOCAL_ROOT
+    # switch off without OUTERLOOP_HOME, so one is always set)
+    local_root = Path(root_s).expanduser() if root_s else default_local_root(environ)
     home = _home(environ, cwd, local=(mode == "local"), root=local_root)
     if mode == "local":
         return StartPlan(
@@ -228,23 +246,22 @@ def plan_start(
     if not root_s:
         raise StartError(
             "Slurm mode needs the state root on the shared filesystem: "
-            "--root, AUTORESEARCH_ROOT, or AUTORESEARCH_ROOT= in ~/.config/outerloop/.env"
+            "--root, OUTERLOOP_ROOT in the environment, or OUTERLOOP_ROOT= in "
+            "~/.config/outerloop/.env"
         )
-    acc = _setting("AUTORESEARCH_ACCOUNT", account, environ, from_file)
-    part = _setting("AUTORESEARCH_PARTITION", partition, environ, from_file)
-    # Partition is optional: left unset, Slurm places the job on its default
-    # partition. Account stays required (clusters bill by it).
-    if not acc:
-        raise StartError("Slurm mode needs --account / AUTORESEARCH_ACCOUNT")
-    minutes_s = _setting("AUTORESEARCH_RESIDENT_MINUTES", "", environ, from_file)
+    acc = _setting("OUTERLOOP_ACCOUNT", account, environ, from_file)
+    part = _setting("OUTERLOOP_PARTITION", partition, environ, from_file)
+    # Account and partition are both optional: left unset, Slurm bills the
+    # caller's default association and places the job on its default partition.
+    minutes_s = _setting("OUTERLOOP_RESIDENT_MINUTES", "", environ, from_file)
     try:
         minutes = int(minutes_s) if minutes_s else DEFAULT_RESIDENT_MINUTES
     except ValueError:
         raise StartError(
-            f"AUTORESEARCH_RESIDENT_MINUTES must be a whole number of minutes, got {minutes_s!r}"
+            f"OUTERLOOP_RESIDENT_MINUTES must be a whole number of minutes, got {minutes_s!r}"
         ) from None
     if minutes <= 0:
-        raise StartError("AUTORESEARCH_RESIDENT_MINUTES must be positive")
+        raise StartError("OUTERLOOP_RESIDENT_MINUTES must be positive")
     # These ride the inherited environment (sbatch --export=ALL), so a comma is
     # safe now (a multi-partition `a,b` is valid) — only a newline would corrupt
     # the environment or the sbatch argv.
@@ -270,16 +287,30 @@ def plan_start(
     )
 
 
+def default_local_root(environ: Mapping[str, str]) -> Path:
+    """The local-mode state root when none is given: ~/.outerloop, or the
+    pre-rename ~/.autoresearch when only that one exists (state is never moved
+    behind the operator's back). The home comes from `environ` so a caller
+    with no HOME gets the plain default."""
+    home_s = environ.get("HOME", "")
+    if not home_s:
+        return DEFAULT_LOCAL_ROOT
+    home = Path(home_s)
+    new, old = home / DEFAULT_LOCAL_ROOT.name, home / LEGACY_LOCAL_ROOT_NAME
+    return old if (not new.exists() and old.is_dir()) else new
+
+
 def _resident_jobs() -> list[str] | None:
-    """Ids of queued or running resident ticks, lowest first; None when the
-    scheduler could not be asked (a failed lookup must never read as 'none')."""
+    """Ids of queued or running resident ticks under either name, lowest first;
+    None when the scheduler could not be asked (a failed lookup must never
+    read as 'none')."""
     try:
         proc = subprocess.run(
             [
                 "squeue",
                 "-u",
                 os.environ.get("USER", ""),
-                f"--name={RESIDENT_JOB_NAME}",
+                f"--name={RESIDENT_JOB_NAME},{LEGACY_RESIDENT_JOB_NAME}",
                 "-h",
                 "-o",
                 "%i",
@@ -309,9 +340,37 @@ def _exec(cmd: list[str], env: dict[str, str]) -> int:
     return 1  # unreachable; keeps the signature honest for tests that stub this
 
 
+HARNESS_BIN_KEYS = ("OUTERLOOP_CLAUDE_BIN", "OUTERLOOP_CODEX_BIN")
+
+
+def _setting_of(key: str, values: Mapping[str, str], environ: Mapping[str, str]) -> str:
+    """The process environment wins over .env, including an explicit empty value
+    (the way to clear a recorded path from the shell)."""
+    return (environ[key] if key in environ else values.get(key, "")).strip()
+
+
+def missing_harness_binary(values: Mapping[str, str], environ: Mapping[str, str]) -> str:
+    """Why start must not launch: the CONFIGURED author backend's recorded
+    binary is not there (init records the path; a moved or uninstalled CLI
+    would end every climb with spawn-error). The other backend's path is not
+    consulted: a stale entry for a backend the loop never spawns must not block
+    it. "" when the binary exists or none is recorded."""
+    backend = _setting_of("OUTERLOOP_AUTHOR_BACKEND", values, environ).lower() or "claude"
+    key = f"OUTERLOOP_{backend.upper()}_BIN"
+    if key not in HARNESS_BIN_KEYS:
+        return ""  # an unknown backend is init's error to report, not this check's
+    path = _setting_of(key, values, environ)
+    if path and not Path(path).expanduser().is_file():
+        return f"{key}={path} is not a file; reinstall the CLI or run `outerloop init --force`"
+    return ""
+
+
 def start(args: argparse.Namespace) -> int:
     try:
         values = env_file_values(ENV_FILE, START_KEYS + TICK_ENV_KEYS)  # one read for everything
+        problem = missing_harness_binary(values, os.environ)
+        if problem:
+            raise StartError(problem)
         from_file = {k: v for k, v in values.items() if k in START_KEYS}
         plan = plan_start(
             root=args.root or "",
@@ -337,14 +396,14 @@ def start(args: argparse.Namespace) -> int:
         for key, value in values.items():
             if key in TICK_ENV_KEYS:
                 env.setdefault(key, value)
-        env["AUTORESEARCH_COMPUTE"] = "local"
-        env["AUTORESEARCH_ROOT"] = str(plan.root)
-        env["AUTORESEARCH_HOME"] = str(plan.home)
+        env["OUTERLOOP_COMPUTE"] = "local"
+        env["OUTERLOOP_ROOT"] = str(plan.root)
+        env["OUTERLOOP_HOME"] = str(plan.home)
         plan.home.mkdir(parents=True, exist_ok=True)  # <root>/home when there is no checkout
         if plan.cadence_min:
-            env["AUTORESEARCH_CADENCE_MIN"] = plan.cadence_min
+            env["OUTERLOOP_CADENCE_MIN"] = plan.cadence_min
         if plan.pat_file:
-            env["AUTORESEARCH_PAT_FILE"] = plan.pat_file
+            env["OUTERLOOP_PAT_FILE"] = plan.pat_file
         print(
             f"local loop: state in {plan.root}; Ctrl-C stops it, the records resume it",
             file=sys.stderr,
@@ -355,14 +414,14 @@ def start(args: argparse.Namespace) -> int:
         print(
             "outerloop start: could not ask the scheduler whether a resident tick "
             "exists (squeue failed); nothing submitted. Retry, or check "
-            f"`squeue --name {RESIDENT_JOB_NAME}`.",
+            f"`squeue --name {RESIDENT_JOB_NAME},{LEGACY_RESIDENT_JOB_NAME}`.",
             file=sys.stderr,
         )
         return 1
     if existing:
         print(
             f"a resident tick is already queued or running (job {existing[0]}); nothing "
-            f"submitted. Stop it with `scancel --name {RESIDENT_JOB_NAME}`, or pause it "
+            f"submitted. Stop it with `scancel {existing[0]}`, or pause it "
             f"with `touch {plan.root}/PAUSE`.",
             file=sys.stderr,
         )
@@ -406,23 +465,40 @@ def start(args: argparse.Namespace) -> int:
 
 
 def main(argv: list[str] | None = None) -> int:
+    from outerloop import __version__
+
     parser = argparse.ArgumentParser(
-        prog="outerloop", description="autonomous research agents in an outer loop"
+        prog="outerloop",
+        description="autonomous research agents in an outer loop",
+        epilog="Run `outerloop init` once, then `outerloop start`. Settings live in "
+        "~/.config/outerloop/.env; the install guide is docs/install.md.",
     )
+    parser.add_argument("--version", action="version", version=f"outerloop {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
     p = sub.add_parser(
-        "start", help="start the loop: the resident tick on Slurm, the local loop elsewhere"
+        "start",
+        help="start the loop: the resident tick on Slurm, the local loop elsewhere",
+        description="Submit the resident tick to Slurm, or run the local loop in the "
+        "foreground where there is no sbatch. Every flag defaults from "
+        "~/.config/outerloop/.env, written by `outerloop init`.",
+    )
+    p.add_argument(
+        "--root", help="state root (shared filesystem on Slurm; default ~/.outerloop locally)"
     )
     p.add_argument(
-        "--root", help="state root (shared filesystem on Slurm; default ~/.autoresearch locally)"
+        "--account", help="Slurm account (optional; unset bills your default association)"
+    )
+    p.add_argument(
+        "--partition",
+        help="Slurm partition for the tick (optional; unset lets Slurm choose; a,b = list)",
     )
-    p.add_argument("--account", help="Slurm account")
-    p.add_argument("--partition", help="Slurm partition for the tick")
     p.add_argument(
         "--local", action="store_true", help="run the local loop even where sbatch exists"
     )
     p.add_argument("--dry-run", action="store_true", help="print the command and exit")
-    sub.add_parser("tick", help="one tick, or --loop; the chain's own entry", add_help=False)
+    sub.add_parser(
+        "tick", help="run one tick now; --loop keeps ticking (the local loop)", add_help=False
+    )
     sub.add_parser(
         "init",
         help="guided setup: write ~/.config/outerloop/.env and the PAT file",

outerloop/compute.py

@@ -95,6 +95,10 @@ class JobSpec:
     # Slurm scheduling controls
     dependency: str = ""  # e.g. "afterany:12345" or "singleton"
     begin: str = ""  # e.g. "now+30" or an absolute "YYYY-MM-DDTHH:MM:SS"
+    # submitted held (PENDING, reason JobHeldUser) until `release`: the
+    # tick's launch admission lets GPU launches into the queue in order,
+    # under the per-user cap, instead of queueing them all at once
+    hold: bool = False
     extra: tuple[str, ...] = ()
 
     def to_argv(self) -> list[str]:
@@ -104,12 +108,13 @@ class JobSpec:
             "sbatch",
             "--parsable",
             f"--job-name={self.job_name}",
-            f"--account={self.account}",
             f"--time={self.time_minutes}",
             f"--cpus-per-task={self.cpus}",
             f"--mem={self.mem}",
             f"--output={self.output}",
         ]
+        if self.account:  # unset bills the caller's default Slurm association
+            argv.append(f"--account={self.account}")
         if self.partition:  # unset lets Slurm pick its default partition
             argv.append(f"--partition={self.partition}")
         if self.gpus:
@@ -120,6 +125,8 @@ class JobSpec:
             argv.append(f"--gpus-per-node={self.gpus}")
         if self.qos:
             argv.append(f"--qos={self.qos}")
+        if self.hold:
+            argv.append("--hold")
         if self.dependency:
             argv.append(f"--dependency={self.dependency}")
         if self.begin:
@@ -133,7 +140,9 @@ class JobSpec:
         return argv
 
 
-QUEUE_FIELDS = ("id", "name", "state", "elapsed", "partition", "submitted")
+# `reason` and `gres` feed launch admission (why a job waits, how many GPUs it
+# asks for); the board reads the first six by key and ignores the rest
+QUEUE_FIELDS = ("id", "name", "state", "elapsed", "partition", "submitted", "reason", "gres")
 
 
 class Compute(Protocol):
@@ -148,15 +157,16 @@ class Compute(Protocol):
     def queue_snapshot(self) -> list[dict[str, str]]: ...
     def job_id_for_name(self, name: str) -> str: ...
     def cancel(self, job_id: str) -> None: ...
+    def release(self, job_id: str) -> None: ...
 
 
 def local_mode() -> bool:
-    """AUTORESEARCH_COMPUTE=local selects the monolith: every job a
+    """OUTERLOOP_COMPUTE=local selects the monolith: every job a
     synchronous subprocess of the caller (docs/design/onboarding.md) — the
     zero-cluster on-ramp and the paper's serialized-baseline ablation. Any
     other value (or none) is Slurm. This helper is the only reader of the
     env var, so mode checks cannot drift."""
-    return os.environ.get("AUTORESEARCH_COMPUTE", "").strip().lower() == "local"
+    return os.environ.get("OUTERLOOP_COMPUTE", "").strip().lower() == "local"
 
 
 def compute_from_env() -> SlurmCompute | LocalCompute:
@@ -267,7 +277,7 @@ class SlurmCompute:
         on failure, like active_job_names."""
         try:
             result = self.runner(
-                ["squeue", "--me", "--noheader", "-o", "%i|%j|%T|%M|%P|%V"],
+                ["squeue", "--me", "--noheader", "-o", "%i|%j|%T|%M|%P|%V|%r|%b"],
                 self.command_timeout_s,
             )
         except (OSError, subprocess.TimeoutExpired) as exc:
@@ -307,6 +317,15 @@ class SlurmCompute:
         if result.returncode != 0:
             log.warning("scancel %s: %s", job_id, result.stderr.strip())
 
+    def release(self, job_id: str) -> None:
+        """Release a job submitted with `hold` so the scheduler may start it.
+        Releasing a job that is not held is not an error."""
+        if not job_id.isdigit():
+            raise ValueError(f"not a job id: {job_id!r}")
+        result = self.runner(["scontrol", "release", job_id], self.command_timeout_s)
+        if result.returncode != 0:
+            log.warning("scontrol release %s: %s", job_id, result.stderr.strip())
+
 
 # Local job ids start far above any real Slurm id so the two can never be
 # confused in a record; they stay numeric because callers validate isdigit.
@@ -318,7 +337,7 @@ def _local_state_dir() -> Path | None:
     attempts it spawns each hold their own LocalCompute): under the state
     root when the deployment names one, else nowhere (memory-only — tests).
     Local jobs are synchronous, so only TERMINAL states ever need sharing."""
-    root = os.environ.get("AUTORESEARCH_ROOT", "").strip()
+    root = os.environ.get("OUTERLOOP_ROOT", "").strip()
     return Path(root) / "local_jobs" if root else None
 
 
@@ -354,7 +373,7 @@ class LocalCompute:
         # the submitting process holds live keys (and any inherited
         # APPTAINERENV_* would cross --cleanenv into the container), so the
         # job script starts from a minimal environment and sets its own.
-        # AUTORESEARCH_* / REVIEW_HERMES_* pass through as a PREFIX rule:
+        # OUTERLOOP_* / REVIEW_HERMES_* pass through as a PREFIX rule:
         # Slurm jobs inherit the tick's whole environment, and local jobs
         # need the same config surface (compute mode, author backend, panel,
         # key-file PATHS). Enumerating allowed names is how a mode flag dies
@@ -368,7 +387,7 @@ class LocalCompute:
             k: v
             for k, v in os.environ.items()
             if k in ("PATH", "HOME", "LANG", "TMPDIR", "SLURM_TMPDIR", "USER", "LOGNAME")
-            or (k.startswith(("AUTORESEARCH_", "REVIEW_HERMES_")) and not _secret_name(k))
+            or (k.startswith(("OUTERLOOP_", "REVIEW_HERMES_")) and not _secret_name(k))
         }
         try:
             # the job runs in its OWN session (= process group), so the
@@ -413,6 +432,13 @@ class LocalCompute:
                 tmp = state_dir / f".{job_id}.{os.getpid()}.tmp"
                 tmp.write_text(state)
                 os.replace(tmp, state_dir / job_id)
+                # the job's combined stdout/stderr beside its state: a failed local
+                # job otherwise leaves nothing to read (#295)
+                out_fd = os.open(
+                    state_dir / f"{job_id}.out", os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600
+                )
+                with os.fdopen(out_fd, "w") as fh:
+                    fh.write(output)
                 # opportunistic prune: one entry per job would leak forever
                 # on a long-running loop; anything the sweep could still want
                 # is far younger than a day
@@ -432,7 +458,12 @@ class LocalCompute:
             except OSError as exc:
                 log.warning("local job %s: output write failed: %s", spec.job_name, exc)
         self._states[job_id] = state
-        log.info("ran %s locally as job %s: %s", spec.job_name, job_id, state)
+        where = (
+            f"; output in {state_dir / (job_id + '.out')}"
+            if state_dir and state != "COMPLETED"
+            else ""
+        )
+        log.info("ran %s locally as job %s: %s%s", spec.job_name, job_id, state, where)
         return job_id
 
     def status(self, job_id: str) -> str:
@@ -471,6 +502,9 @@ class LocalCompute:
             raise ValueError(f"not a job id: {job_id!r}")
         # already terminal; cancelling a finished job is not an error
 
+    def release(self, job_id: str) -> None:
+        """Local jobs run synchronously at submit; nothing is ever held."""
+
 
 def parse_elapsed(text: str) -> int | None:
     """Seconds in a sacct Elapsed field: `MM:SS`, `HH:MM:SS` or `D-HH:MM:SS`.
@@ -504,6 +538,22 @@ def is_pending(state: str) -> bool:
     return state.startswith("PENDING")
 
 
+def gpus_in_gres(gres: str) -> int:
+    """GPUs a queue row asks for, from squeue's %b (`gres/gpu:8`,
+    `gres/gpu:h200:2`, `gres:gpu:4`; `N/A` or anything else = 0)."""
+    total = 0
+    for part in gres.replace(";", ",").split(","):
+        fields = part.strip().split(":")
+        if (len(fields) >= 2 and fields[0] in ("gres/gpu", "gpu")) or (
+            len(fields) >= 3 and fields[0] == "gres" and fields[1] == "gpu"
+        ):
+            try:
+                total += int(fields[-1])
+            except ValueError:
+                continue
+    return total
+
+
 def quote_command(parts: Sequence[str]) -> str:
     """Shell-quote a command for JobSpec.command (--wrap takes a string)."""
     return " ".join(shlex.quote(p) for p in parts)

outerloop/contract.py

@@ -26,6 +26,7 @@ SELF_REPO = "outerloop-science/outerloop"
 # `.autoresearch.yaml` (targets written before the rename) is still honored. Every
 # read goes through `find_contract`, which tries the new name first. Neither is
 # ever a writable path for the agent.
+# The pre-rename name is dropped in the release after 0.1.
 CONTRACT_NAMES: tuple[str, ...] = (".outerloop.yaml", ".autoresearch.yaml")
 CONTRACT_NAME = CONTRACT_NAMES[0]  # what the docs and new contracts use
 ALWAYS_FORBIDDEN: tuple[str, ...] = (".github", *CONTRACT_NAMES)
@@ -126,8 +127,8 @@ class Benchmark(_StrictModel):
     eval_minutes: int | None = Field(default=None, ge=1)
     # GPUs for every dispatched job of this benchmark — gate measures and
     # author launches alike. 0 (default) = CPU. A GPU benchmark needs the
-    # deployment to name a GPU lane (AUTORESEARCH_GPU_PARTITION, optionally
-    # AUTORESEARCH_GPU_ACCOUNT); without one the tick refuses to launch
+    # deployment to name a GPU lane (OUTERLOOP_GPU_PARTITION, optionally
+    # OUTERLOOP_GPU_ACCOUNT); without one the tick refuses to launch
     # attempts on it rather than queue evals that can never run. Bounded at
     # one node's worth: multi-node evals are not a shape the jail supports.
     gpus: int = Field(default=0, ge=0, le=8)