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

outerloop/syscall.py

@@ -36,13 +36,14 @@ import contextlib
 import json
 import os
 import re
+import stat
 from collections.abc import Callable, Iterable
 from dataclasses import dataclass, replace
 from pathlib import Path
 from time import monotonic
 from typing import Any
 
-from outerloop.brief import _fence
+from outerloop.brief import code_fence
 from outerloop.compute import GONE
 
 # The syscall channel dir in the workspace. New runs install `.outerloop/`;
@@ -87,6 +88,10 @@ MAX_LAUNCH_ARRAY = 16
 MAX_COMMAND_CHARS = 2_000
 MAX_ARTIFACTS_PER_LAUNCH = 8
 MAX_NOTE_CHARS = 2_000
+# a launch's one-line reason, shown to every agent in the queue view
+MAX_WHY_CHARS = 200
+# the author's write-up at submit: hypothesis, what ran, what was measured, why merge
+MAX_REPORT_CHARS = 8_000
 # Per-job walltime ask, clamped to the same ceiling as dispatched evals.
 MAX_LAUNCH_MINUTES = 240
 # a submit's declared eval walltime: bounded only by the GPU-hour budget the
@@ -127,6 +132,11 @@ class Launch:
     # a sweep: N jobs of this command, each told its index through SWEEP_INDEX;
     # one launch against depth_k, N times the walltime against GPU-hours
     array: int = 1
+    # the author's one-line reason; the queue view shows it to every agent
+    why: str = ""
+    # a sweep's pace: at most this many tasks at once (0 = the whole array);
+    # the kernel clamps it to the contract's GPU ceiling (`clamp_concurrency`)
+    concurrency: int = 0
 
 
 @dataclass(frozen=True)
@@ -140,6 +150,9 @@ class SyscallRequest:
     # wake returns verdict + gate result to the author (published directly when
     # it clears cleanly). Costs the sleep it rides on, nothing else.
     submit: bool = False
+    # the author's report at submit, required with one: it becomes the pull
+    # request's research report and the panel reads it against the diff
+    report: str = ""
     # The author's declared walltime for the submit's paired gate evals
     # (None = the contract's eval_minutes). Walltime is a budget, never the
     # metric: compute is priced in GPU-hours against the run's budget, so a
@@ -162,6 +175,7 @@ class LaunchResult:
     # code (an untrappable SIGKILL — OOM, walltime kill, node failure — writes
     # none). "" when known from the exit code, unavailable, or unqueried.
     slurm_state: str = ""
+    why: str = ""  # the launch's reason, echoed with its result
 
 
 def launch_jobs(launch: Launch) -> tuple[tuple[str, dict[str, str]], ...]:
@@ -176,6 +190,50 @@ def launch_jobs(launch: Launch) -> tuple[tuple[str, dict[str, str]], ...]:
     return tuple((f"{launch.name}.{i}", {"SWEEP_INDEX": str(i)}) for i in range(launch.array))
 
 
+def array_spec(launch: Launch) -> str:
+    """The Slurm array spec for a sweep: tasks 0..N-1, at most `concurrency`
+    at a time (the whole array when unset). "" for a plain launch."""
+    if launch.array <= 1:
+        return ""
+    return f"0-{launch.array - 1}%{launch.concurrency or launch.array}"
+
+
+def clamp_concurrency(
+    request: SyscallRequest, *, gpus: int, max_concurrent_gpus: int | None
+) -> SyscallRequest:
+    """Apply the contract's ceiling to every sweep: the tasks one launch may
+    run at once is `max_concurrent_gpus // gpus` (a two-GPU task gets half the
+    tasks of a one-GPU task and the same share of the machine), never below
+    one; a request above it is clamped, never refused. No ceiling: the
+    author's pace stands, the whole array by default."""
+    if not max_concurrent_gpus:
+        return request
+    cap = max(1, max_concurrent_gpus // max(gpus, 1))
+    launches = tuple(
+        replace(la, concurrency=min(la.concurrency or la.array, cap)) if la.array > 1 else la
+        for la in request.launches
+    )
+    return replace(request, launches=launches)
+
+
+def launch_task_ids(launches: Iterable[Launch], job_ids: list[str]) -> list[str]:
+    """The per-task job ids of a park's launches, aligned with `launch_jobs`
+    order (what results, states and refunds are keyed by). A sweep is one
+    Slurm job whose tasks are `<id>_<k>`, so one id per launch expands; a park
+    recorded before arrays were single jobs already carries one id per task
+    and passes through. Anything else is an unknown mapping: no ids, so no
+    caller guesses."""
+    launches = list(launches)
+    if len(job_ids) == len(launches):
+        out: list[str] = []
+        for la, jid in zip(launches, job_ids, strict=True):
+            out.extend([f"{jid}_{k}" for k in range(la.array)] if la.array > 1 else [jid])
+        return out
+    if len(job_ids) == sum(max(la.array, 1) for la in launches):
+        return list(job_ids)
+    return []
+
+
 def _rel_path_ok(path: str) -> bool:
     """A declared artifact must stay inside the job's tree: repo-relative,
     no traversal, no absolute paths. (Same stance as scope normalization.)"""
@@ -218,7 +276,7 @@ def read_request(workspace: Path) -> SyscallRequest | None:
     # so anything else here (e.g. a verdict) is a wrong-type request, not a sleep.
     if data.get("type") != "sleep":
         raise SyscallError(f"expected a sleep syscall, got type {data.get('type')!r}")
-    unknown = set(data) - {"type", "launches", "note", "submit", "eval_minutes"}
+    unknown = set(data) - {"type", "launches", "note", "submit", "eval_minutes", "report"}
     if unknown:
         raise SyscallError(f"unknown syscall keys: {sorted(unknown)}")
     note = data.get("note", "")
@@ -234,6 +292,9 @@ def read_request(workspace: Path) -> SyscallRequest | None:
         if not submit:
             raise SyscallError("eval_minutes only applies to a submit")
         eval_minutes = min(eval_minutes, MAX_EVAL_MINUTES)
+    report = data.get("report", "")
+    if not isinstance(report, str) or len(report) > MAX_REPORT_CHARS:
+        raise SyscallError(f"report must be a string of at most {MAX_REPORT_CHARS} chars")
     raw_launches = data.get("launches", [])
     if not isinstance(raw_launches, list):
         raise SyscallError("launches must be a list")
@@ -244,7 +305,7 @@ def read_request(workspace: Path) -> SyscallRequest | None:
     for i, item in enumerate(raw_launches):
         if not isinstance(item, dict):
             raise SyscallError(f"launch #{i} must be an object")
-        bad = set(item) - {"name", "command", "minutes", "artifacts", "array"}
+        bad = set(item) - {"name", "command", "minutes", "artifacts", "array", "why", "concurrency"}
         if bad:
             raise SyscallError(f"launch #{i}: unknown keys {sorted(bad)}")
         name = item.get("name")
@@ -266,6 +327,16 @@ def read_request(workspace: Path) -> SyscallRequest | None:
         if not isinstance(array, int) or isinstance(array, bool) or array < 1:
             raise SyscallError(f"launch {name}: array must be a positive integer")
         array = min(array, MAX_LAUNCH_ARRAY)
+        concurrency = item.get("concurrency", 0)
+        if not isinstance(concurrency, int) or isinstance(concurrency, bool) or concurrency < 0:
+            raise SyscallError(f"launch {name}: concurrency must be a non-negative integer")
+        concurrency = min(concurrency, array) if array > 1 else 0
+        why = item.get("why", "")
+        if not isinstance(why, str) or len(why) > MAX_WHY_CHARS:
+            raise SyscallError(
+                f"launch {name}: why must be a string of at most {MAX_WHY_CHARS} chars"
+            )
+        why = " ".join(why.split())  # one line: it is rendered inline where other agents read
         arts = item.get("artifacts", [])
         if not isinstance(arts, list) or len(arts) > MAX_ARTIFACTS_PER_LAUNCH:
             raise SyscallError(
@@ -278,13 +349,25 @@ def read_request(workspace: Path) -> SyscallRequest | None:
                     f"launch {name}: artifact {a!r} must be a repo-relative file path"
                 )
         launches.append(
-            Launch(name=name, command=command, minutes=minutes, artifacts=tuple(arts), array=array)
+            Launch(
+                name=name,
+                command=command,
+                minutes=minutes,
+                artifacts=tuple(arts),
+                array=array,
+                why=why,
+                concurrency=concurrency,
+            )
         )
     # a sleep with no launches is legitimate: checkpoint-and-reschedule
     # (research-loop.md, "the session clock is visible") — it still burns a
     # sleep count, which is what bounds living forever.
     return SyscallRequest(
-        launches=tuple(launches), note=note, submit=submit, eval_minutes=eval_minutes
+        launches=tuple(launches),
+        note=note,
+        submit=submit,
+        eval_minutes=eval_minutes,
+        report=report.strip(),
     )
 
 
@@ -449,14 +532,16 @@ def _validate_finding(i: int, item: Any) -> dict[str, Any]:
     # Absent or "" is legitimately "no category".
     if not isinstance(category, str):
         raise VerdictError(f"finding {file}: category must be a string")
-    if category:  # verifier-only; a non-empty string
-        # (str here, so `in CATEGORIES` cannot raise on unhashables) — CLAMP an
+    if category:  # a non-empty string: the verifier's taxonomy or a digest section
+        # (str here, so membership cannot raise on unhashables) — CLAMP an
         # unknown category to "other" rather than reject, the existing verifier
         # stance (verifier.py: "a free-string category must not leak through"),
         # so a taxonomy typo normalizes instead of nuking a verdict.
+        from outerloop.maintain import MAINTENANCE_LENSES
         from outerloop.verifier import CATEGORIES
 
-        out["category"] = category if category in CATEGORIES else "other"
+        known = category in CATEGORIES or category in MAINTENANCE_LENSES
+        out["category"] = category if known else "other"
     return out
 
 
@@ -512,6 +597,77 @@ def install_tool(workspace: Path) -> None:
     tool.chmod(0o755)
 
 
+MISSING_REPORT = (
+    "a submit needs a report. Write your hypothesis, what you ran and what it measured, "
+    "why this should merge and what did not work to a markdown file, stage "
+    "`submit --report <file>`, and sleep again."
+)
+
+
+def tool_update_note(channel: str) -> str:
+    """What a session that started under an older kernel is told at a wake
+    whose tool refresh replaced its tool; `channel` is this workspace's channel
+    dir name (a resumed legacy session still has `.autoresearch`)."""
+    return (
+        "Your syscall tool was updated. `submit` now requires `--report <file>`. The "
+        "report explains your hypothesis, what you ran and measured, why this should "
+        "merge, and what did not work; it becomes the pull request's research report "
+        "and the panel reads it. `launch` accepts `--why` and, with `--array`, "
+        "`--concurrency K`. `queue` shows every agent's jobs; `history` shows your "
+        f"launches this run. `python {channel}/syscall <verb> --help` has the details."
+    )
+
+
+def refresh_tool(workspace: Path) -> bool:
+    """Rewrite the installed tool from this kernel's source at a wake, so a
+    session that started under an older kernel gets the current verbs and
+    flags. Only the tool file changes — the channel and everything in it
+    stay — and it is written with a marker's care (a fresh O_EXCL inode,
+    renamed into place), so a `syscall` the session replaced with a symlink
+    is never written through. Returns whether the tool changed, so the wake
+    can tell the author what is new."""
+    import shutil
+
+    from outerloop import syscall_cli
+
+    source = Path(syscall_cli.__file__).read_bytes()
+    dirfd = _channel_fd(workspace)
+    try:
+        try:
+            st = os.stat("syscall", dir_fd=dirfd, follow_symlinks=False)
+        except FileNotFoundError:
+            st = None
+        current: bytes | None = None
+        if st is not None and stat.S_ISREG(st.st_mode) and st.st_size == len(source):
+            # compare through a non-blocking open checked after the fact: a FIFO
+            # swapped in since the stat returns at once instead of waiting for a
+            # writer, and anything unreadable (mode 000) simply gets rewritten
+            try:
+                fd = os.open("syscall", os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=dirfd)
+            except OSError:
+                fd = -1
+            if fd >= 0:
+                try:
+                    if stat.S_ISREG(os.fstat(fd).st_mode):
+                        current = os.read(fd, len(source) + 1)
+                except OSError:
+                    current = None
+                finally:
+                    os.close(fd)
+        if current == source:
+            return False  # already this kernel's tool, readable as it should be
+        if st is not None and stat.S_ISDIR(st.st_mode):
+            # a directory planted in the tool's place: rename cannot replace
+            # it. Removed RELATIVE TO THE CHANNEL FD, never by path — a path
+            # would be re-resolved, and a channel swapped for a symlink in
+            # between would send the removal outside the workspace
+            shutil.rmtree("syscall", dir_fd=dirfd)
+        _write_channel(dirfd, "syscall", source, mode=0o755)
+        return True
+    finally:
+        os.close(dirfd)
+
+
 def write_budget(
     workspace: Path,
     *,
@@ -604,6 +760,41 @@ def budget_error(
     return ""
 
 
+def _job_outcome(ev: Path) -> tuple[int | None, str, str, tuple[str, ...]]:
+    """What one launch job left in its dir: exit code (None = it died before
+    its wrapper ran), stdout/stderr tails, and the copy-out's skip lines."""
+    try:
+        exit_code: int | None = int((ev / "exit-code").read_text().strip())
+    except (OSError, ValueError):
+        exit_code = None
+    stdout = _read_tail(ev / "stdout", MAX_OUTPUT_CHARS)
+    stderr = _read_tail(ev / "stderr", MAX_OUTPUT_CHARS)
+    skipped = tuple(ln for ln in _read_text(ev / "artifacts.log").splitlines() if ln.strip())
+    return exit_code, stdout, stderr, skipped
+
+
+def read_results(run_dir: Path, launches: tuple[Launch, ...]) -> tuple[LaunchResult, ...]:
+    """Each launch job's outcome as it sits in the run dir — no delivery into
+    any workspace. For the ledger, and for a wake that publishes without
+    resuming the author (`gather_results` is the delivering form)."""
+    results: list[LaunchResult] = []
+    for launch in launches:
+        for job_name, _env in launch_jobs(launch):
+            exit_code, stdout, stderr, skipped = _job_outcome(run_dir / f"eval-launch-{job_name}")
+            results.append(
+                LaunchResult(
+                    name=job_name,
+                    exit_code=exit_code,
+                    stdout_tail=stdout,
+                    stderr_tail=stderr,
+                    delivered=(),
+                    skipped=skipped,
+                    why=launch.why,
+                )
+            )
+    return tuple(results)
+
+
 def gather_results(
     run_dir: Path, workspace: Path, launches: tuple[Launch, ...]
 ) -> tuple[LaunchResult, ...]:
@@ -626,16 +817,7 @@ def gather_results(
         # with artifacts under results/<launch>/<i>/
         for i, (job_name, _env) in enumerate(launch_jobs(launch)):
             ev = run_dir / f"eval-launch-{job_name}"
-            try:
-                exit_code: int | None = int((ev / "exit-code").read_text().strip())
-            except (OSError, ValueError):
-                exit_code = None
-            stdout = _read_tail(ev / "stdout", MAX_OUTPUT_CHARS)
-            stderr = _read_tail(ev / "stderr", MAX_OUTPUT_CHARS)
-            skipped = tuple(
-                ln for ln in _read_text(ev / "artifacts.log").splitlines() if ln.strip()
-            )
-
+            exit_code, stdout, stderr, skipped = _job_outcome(ev)
             delivered, skips = _deliver_artifacts(
                 ev / "artifacts", workspace, launch.name, index=i if launch.array > 1 else None
             )
@@ -647,6 +829,7 @@ def gather_results(
                     stderr_tail=stderr,
                     delivered=delivered,
                     skipped=skipped + skips,
+                    why=launch.why,
                 )
             )
     return tuple(results)
@@ -832,14 +1015,15 @@ def render_wake(
     data-fenced exactly like panel findings."""
     blocks: list[str] = []
     for r in results:
-        lines = [f"launch `{r.name}` — exit code: {_exit_code_line(r)}"]
+        why = f" ({r.why})" if r.why else ""
+        lines = [f"launch `{r.name}`{why} — exit code: {_exit_code_line(r)}"]
         if r.delivered:
             lines.append("artifacts delivered: " + ", ".join(f"`{p}`" for p in r.delivered))
         if r.skipped:
             lines.append("artifacts NOT delivered: " + "; ".join(r.skipped))
         body = _tail(r.stdout_tail) or "(empty)"
         err = _tail(r.stderr_tail)
-        fence = _fence(body + err)
+        fence = code_fence(body + err)
         lines.append(f"stdout (tail):\n{fence}\n{body}\n{fence}")
         if err:
             lines.append(f"stderr (tail):\n{fence}\n{err}\n{fence}")
@@ -852,7 +1036,7 @@ def render_wake(
         joined,
     ]
     if note:
-        fence = _fence(note)
+        fence = code_fence(note)
         parts.append(f"Your note to yourself:\n{fence}\n{note}\n{fence}")
     gpu = f", {gpu_hours_remaining:.1f} GPU-hours" if gpu_hours_remaining is not None else ""
     # Push to keep going ONLY when another launch is actually possible: a launch
@@ -918,15 +1102,20 @@ def _channel_fd(workspace: Path) -> int:
     return os.open(workspace / channel_dir(workspace), os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
 
 
-def _read_done(dirfd: int) -> float:
+def _read_done(dirfd: int, name: str = SYNC_DONE) -> float:
     """The mtime the kernel last acknowledged (stored as marker CONTENT, so
     no mtime games: hard-linking the marker cannot change another file's
     times, because the kernel never calls utime)."""
     try:
-        fd = os.open(SYNC_DONE, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=dirfd)
+        # O_NONBLOCK: opening a FIFO planted in the marker's place returns at
+        # once instead of waiting for a writer that never comes (the watcher
+        # thread and the tick would otherwise hang on it forever)
+        fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=dirfd)
     except OSError:
         return 0.0
     try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            return 0.0  # a FIFO, socket or device is not a marker the kernel wrote
         return float(os.read(fd, 64).decode() or 0)
     except (OSError, ValueError):
         return 0.0
@@ -934,10 +1123,30 @@ def _read_done(dirfd: int) -> float:
         os.close(fd)
 
 
-def sync_requested(workspace: Path) -> float | None:
-    """The pending request's mtime, or None. Passed back to mark_synced so
-    the done marker acknowledges exactly the serviced request — one arriving
-    mid-fetch stays newer and re-fires. A symlinked channel or request is
+def _write_channel(dirfd: int, name: str, data: bytes, mode: int = 0o644) -> None:
+    """Write `data` to `name` in the channel: a fresh O_EXCL temp inode with an
+    unguessable name, then an atomic rename — all relative to the O_NOFOLLOW
+    channel fd. Never opens (and O_TRUNCs) an existing inode, so a session
+    that hard-links a victim file to the temp name gets a failure instead of a
+    truncation; never writes through a planted symlink; never utime()s."""
+    tmp = f".{name}.{os.urandom(8).hex()}"
+    fd = os.open(tmp, os.O_CREAT | os.O_EXCL | os.O_WRONLY | os.O_NOFOLLOW, mode, dir_fd=dirfd)
+    try:
+        # the open's mode is filtered by the umask; the tool must stay executable
+        os.fchmod(fd, mode)
+        view = memoryview(data)
+        while view:
+            written = os.write(fd, view)
+            view = view[written:]
+    finally:
+        os.close(fd)
+    os.replace(tmp, name, src_dir_fd=dirfd, dst_dir_fd=dirfd)
+
+
+def marker_requested(workspace: Path, request: str, done: str) -> float | None:
+    """The pending request's mtime, or None. Passed back to `mark_done` so the
+    done marker acknowledges exactly the serviced request — one arriving
+    mid-service stays newer and re-fires. A symlinked channel or request is
     refused (returns None), never followed."""
     try:
         dirfd = _channel_fd(workspace)
@@ -945,34 +1154,39 @@ def sync_requested(workspace: Path) -> float | None:
         return None
     try:
         try:
-            st = os.stat(SYNC_REQUEST, dir_fd=dirfd, follow_symlinks=False)
+            st = os.stat(request, dir_fd=dirfd, follow_symlinks=False)
         except OSError:
             return None
         req_m = st.st_mtime
-        return req_m if req_m > _read_done(dirfd) else None
+        return req_m if req_m > _read_done(dirfd, done) else None
     finally:
         os.close(dirfd)
 
 
-def mark_synced(workspace: Path, at: float) -> None:
-    """Record the serviced request's mtime as the done marker's CONTENT,
-    written to a fresh temp inode and renamed into place — all relative to a
-    O_NOFOLLOW channel fd. No utime (so a hard-linked marker cannot touch
-    another file), no write through a planted symlink (O_NOFOLLOW create),
-    no parent-symlink escape (the channel fd was opened O_NOFOLLOW), and the
-    rename is atomic."""
+def mark_done(workspace: Path, done: str, at: float) -> None:
+    """Record the serviced request's mtime as the done marker's CONTENT."""
     dirfd = _channel_fd(workspace)
     try:
-        # O_EXCL + an unguessable name: never open (and O_TRUNC) an existing
-        # inode. A session that hard-links a victim file to the temp name
-        # would otherwise have it truncated — O_EXCL fails on any pre-existing
-        # name instead, and O_NOFOLLOW refuses a symlink.
-        tmp = f".{SYNC_DONE}.{os.urandom(8).hex()}"
-        fd = os.open(tmp, os.O_CREAT | os.O_EXCL | os.O_WRONLY | os.O_NOFOLLOW, 0o644, dir_fd=dirfd)
-        try:
-            os.write(fd, f"{at!r}".encode())
-        finally:
-            os.close(fd)
-        os.replace(tmp, SYNC_DONE, src_dir_fd=dirfd, dst_dir_fd=dirfd)
+        _write_channel(dirfd, done, f"{at!r}".encode())
+    finally:
+        os.close(dirfd)
+
+
+def write_channel_json(workspace: Path, name: str, payload: object) -> None:
+    """A kernel answer the session reads (`queue.json`, `history.json`),
+    written with a marker's care: the session may have replaced anything in
+    the channel while the kernel was not looking."""
+    dirfd = _channel_fd(workspace)
+    try:
+        _write_channel(dirfd, name, json.dumps(payload).encode())
     finally:
         os.close(dirfd)
+
+
+def sync_requested(workspace: Path) -> float | None:
+    """The pending sync request's mtime, or None (see `marker_requested`)."""
+    return marker_requested(workspace, SYNC_REQUEST, SYNC_DONE)
+
+
+def mark_synced(workspace: Path, at: float) -> None:
+    mark_done(workspace, SYNC_DONE, at)