outerloop-science 0.1.0.dev0__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,48 +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_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",
 )
@@ -88,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
 
 
@@ -123,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]:
@@ -146,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
@@ -165,19 +184,23 @@ def _setting(key: str, flag: str, environ: dict[str, str], from_file: dict[str,
     return from_file.get(key, "")
 
 
-def _home(environ: dict[str, str], cwd: Path) -> Path:
-    """The checkout the loop runs from: AUTORESEARCH_HOME, else the current
-    directory when it is one. Both modes need it; the tick's launch lanes
-    and GitHub servicing switch off without it."""
-    home = (
-        Path(environ["AUTORESEARCH_HOME"]).expanduser() if environ.get("AUTORESEARCH_HOME") else cwd
+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 (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
+    under the state root, where flights and logs land."""
+    named = environ.get("OUTERLOOP_HOME") or environ.get("AUTORESEARCH_HOME")
+    home = Path(named).expanduser() if named else cwd
+    if (home / "scripts" / "tick_chain.sbatch").is_file():
+        return home
+    if local and not named:
+        return root / "home"
+    raise StartError(
+        f"{home} is not a source checkout (no scripts/tick_chain.sbatch); "
+        "run start from a clone of the kernel, or set OUTERLOOP_HOME to one"
     )
-    if not (home / "scripts" / "tick_chain.sbatch").is_file():
-        raise StartError(
-            f"{home} is not an autoresearch checkout (no scripts/tick_chain.sbatch); "
-            "run start from the checkout the chain should deploy from, or set AUTORESEARCH_HOME"
-        )
-    return home
 
 
 def plan_start(
@@ -191,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
@@ -204,16 +227,18 @@ 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)
-    # both modes run from a checkout: the tick's launch lanes and GitHub
-    # servicing switch off without AUTORESEARCH_HOME
-    home = _home(environ, cwd)
+    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 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(
             mode="local",
-            root=Path(root_s).expanduser() if root_s else DEFAULT_LOCAL_ROOT,
+            root=local_root,
             home=home,
             cadence_min=cadence,
             pat_file=pat,
@@ -221,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.
@@ -263,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",
@@ -302,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 "",
@@ -330,13 +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,
@@ -347,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,
         )
@@ -398,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",