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

outerloop/tick.py

@@ -36,7 +36,6 @@ from outerloop.compute import (
     SlurmError,
     SlurmQueryError,
     compute_from_env,
-    gpus_in_gres,
     is_pending,
     is_terminal,
     local_mode,
@@ -97,8 +96,7 @@ BLIND_PARK_SLACK_MIN = 12 * 60
 # would put it at the back of the queue behind itself. Per-job limits
 # (`...PerJob...`), a dependency that can never be satisfied, an invalid
 # account/QOS or a held job are NOT waits: those never clear on their own.
-# JobHeldUser is the kernel's own launch admission (service_admission): a
-# held launch waits for a GPU slot, and an operator's hold is theirs to lift.
+# JobHeldUser: an operator's hold is theirs to lift; the job is waiting, not stuck.
 QUEUE_WAIT_REASONS = frozenset(
     {"Priority", "Resources", "Reservation", "Dependency", "ReqNodeNotAvail", "JobHeldUser"}
 )
@@ -148,18 +146,6 @@ class WakeDispatcher(Protocol):
     def dispatch(self, record: RunRecord, reason: str) -> str: ...
 
 
-@dataclass
-class RecordingDispatcher:
-    """Test/dry-run dispatcher: records what would have been woken."""
-
-    dispatched: list[tuple[str, str]] = field(default_factory=list)
-    holder_job_id: str = ""  # set to simulate async dispatch
-
-    def dispatch(self, record: RunRecord, reason: str) -> str:
-        self.dispatched.append((record.run_id, reason))
-        return self.holder_job_id
-
-
 @dataclass(frozen=True)
 class TickReport:
     paused: bool = False
@@ -244,11 +230,6 @@ class FollowupSpec:
     # are minutes, work jobs can be hours, and Slurm prices walltime into
     # scheduling priority, so the two deserve independent placement.
     job_partition: str = ""
-    # Launch admission: the most GPUs this user's jobs may hold at once
-    # (OUTERLOOP_MAX_LAUNCH_GPUS, e.g. the QOS's MaxTRESPerUser). 0 = off:
-    # launches queue as submitted. On, GPU launches are submitted held and
-    # service_admission releases them oldest-first under the cap.
-    max_launch_gpus: int = 0
     # Partition MaxTime for work jobs — the panel-augmented walltime clamps
     # here (see MAX_ATTEMPT_JOB_MINUTES). Raise together with job_partition.
     max_job_minutes: int = MAX_ATTEMPT_JOB_MINUTES
@@ -424,7 +405,7 @@ def contract_alarm(
     target: str,
     error: str | None,
     now: float,
-    bot_login: str = "agentic-learning-bot",
+    bot_login: str = "",
 ) -> None:
     """Persistent contract failure must surface where humans look.
 
@@ -433,6 +414,7 @@ def contract_alarm(
     opens ONE issue on the target repo; the next successful load closes
     it and says so. Alarm plumbing is best-effort by construction: it
     must never break the tick it reports for."""
+    bot_login = bot_login or _bot_login_default()
     state_path = root / "contract-alarm.json"
     try:
         state = json.loads(state_path.read_text())
@@ -894,7 +876,8 @@ def _last_worked_ts(root: Path) -> float | None:
             return None
         val = float(ts)
         return val if math.isfinite(val) else None
-    except Exception:
+    except Exception as exc:
+        log.debug("work marker unreadable, coalescing as if absent: %s", exc)
         return None
 
 
@@ -1192,6 +1175,11 @@ def sweep(
         except Exception as exc:
             log.warning("sweep failed on %s: %s: %s", record.run_id, type(exc).__name__, exc)
 
+    try:
+        cancel_ended_launches(root, compute, now, dry_run)
+    except Exception as exc:
+        log.warning("cancel-on-end failed: %s: %s", type(exc).__name__, exc)
+
     return TickReport(
         swept=len(records),
         woken=tuple(woken),
@@ -1205,6 +1193,64 @@ def sweep(
     )
 
 
+CANCEL_ON_END_WINDOW_S = 7 * 86400
+
+
+def cancel_ended_launches(
+    root: Path, compute: Compute, now: float, dry_run: bool = False
+) -> list[str]:
+    """Cancel on end: a run that ended while its author's launches are still
+    queued or running has nothing left to read their results, so the jobs are
+    cancelled — a running one included, since that is the one holding GPUs for
+    a result nobody will read. The stage is stamped once every cancel
+    succeeded, so an ended run costs no query afterwards; a failed scancel
+    leaves the run unstamped for the next tick, and runs ended longer ago than
+    the window are stamped without a query (their jobs have long left the
+    queue). Returns the cancelled ids."""
+    from outerloop.attempt import stage_launch_job_ids
+
+    cancelled: list[str] = []
+    for record in list_runs(root):
+        if record.state != ENDED:
+            continue
+        stage = dict(record.stage or {})
+        if stage.get("launches_cancelled"):
+            continue
+        job_ids = stage_launch_job_ids(record)
+        recent = now - float(getattr(record, "updated", 0.0) or 0.0) <= CANCEL_ON_END_WINDOW_S
+        live: list[str] = []
+        if job_ids and recent:
+            try:
+                for jid in job_ids:
+                    state = compute.status(jid)
+                    if state != GONE and not is_terminal(state):
+                        live.append(jid)
+            except SlurmQueryError as exc:
+                log.warning("cancel-on-end: %s: query failed (%s); next tick", record.run_id, exc)
+                continue
+        if dry_run:
+            cancelled.extend(live)
+            continue
+        failed = False
+        for jid in live:
+            try:
+                ok = compute.cancel(jid)
+            except Exception as exc:
+                ok = False
+                log.warning("cancel-on-end: %s: scancel %s failed: %s", record.run_id, jid, exc)
+            if ok:
+                cancelled.append(jid)
+            else:
+                failed = True
+        if failed:
+            continue  # unstamped: the next tick tries again, until the window closes
+        stage["launches_cancelled"] = True
+        save_record(root, replace(record, stage=stage), now)
+    if cancelled:
+        log.info("cancel-on-end: cancelled %d launch job(s) of ended runs", len(cancelled))
+    return cancelled
+
+
 RESEARCH_LOG_BRANCH = "research-log"
 RESEARCH_LOG_MARKER = marker("research-log")
 RESEARCH_LOG_PER_TICK = 3
@@ -1793,6 +1839,12 @@ def tick(
     # whether github/contract loaded this tick.
     if followup_spec is not None:
         service_syncs(root, followup_spec, now)
+    # a dry run reports and writes nothing: no download, no seed
+    if github is not None and followup_spec is not None and followup_spec.target and not dry_run:
+        try:
+            service_eval_cache(root, github, followup_spec.target)
+        except Exception as exc:  # advisory: a cold cache costs a download, never a tick
+            log.warning("eval cache warm failed: %s: %s", type(exc).__name__, exc)
     if github is not None and followup_spec is not None:
         # expired flight snapshots die with their TTL, not with a human.
         # One home suffices: every lane's spec derives from followup_spec
@@ -1863,12 +1915,6 @@ def tick(
             allow_submit=launch_ok,
             contract=contract,
         )
-        # ended runs are known now, so a held launch of an ended run is dropped
-        # and a GPU slot freed by a finished eval is handed to the oldest held one
-        try:
-            service_admission(root, compute, spec, dry_run=followup_dry_run)
-        except Exception as exc:  # admission is advisory to the tick
-            log.warning("admission service failed: %s", exc)
         try:
             service_research_log(root, github, spec, now)
         except Exception as exc:  # the ledger is advisory; the tick continues
@@ -1920,118 +1966,16 @@ def tick(
     return report
 
 
-LAUNCH_MARK = "-launch-"  # every author launch job is named <run_id>-launch-<name>
+def service_eval_cache(root: Path, github: Any, target: str) -> str:
+    """Warm the target's seed cache from its default branch's lockfile
+    (docs/design/eval-cache.md). Cheap when nothing changed: two file reads
+    and a hash. Returns the warmer's one-word status."""
+    from outerloop.evalcache import warm
 
-
-@dataclass(frozen=True)
-class AdmissionReport:
-    released: tuple[str, ...] = ()  # job ids let into the queue this tick
-    dropped: tuple[str, ...] = ()  # held launches of runs that already ended
-    held: int = 0  # still waiting after this tick
-    gpus_in_use: int = 0  # GPUs held by this user's eligible jobs, after releases
-
-
-def _cap_reason(reason: str) -> bool:
-    head = reason.strip().split(",")[0].split(" ")[0]
-    return any(tag in head for tag in ("PerUser", "PerAccount", "Grp")) and "PerJob" not in head
-
-
-def service_admission(
-    root: Path, compute: Compute, spec: FollowupSpec, *, dry_run: bool = False
-) -> AdmissionReport:
-    """Launch admission (Torch 2026-09-06: six 8-GPU launches queued against a
-    16-GPU per-user cap, four of them pending for a day on QOSMaxGRESPerUser).
-    Author launches are submitted HELD when a cap is configured; every tick
-    this releases them oldest-first while the user's eligible GPU jobs (evals
-    and launches alike) fit under the cap, and cancels held launches whose run
-    has already ended. A released launch that Slurm then parks on a per-user
-    reason means the configured cap is too high: nothing more is released
-    that tick. Off (cap 0) and in local mode this does nothing. A failed
-    queue read releases nothing (blind is never "free")."""
-    if local_mode():
-        return AdmissionReport()  # local jobs are synchronous; nothing is ever held
-    try:
-        rows = compute.queue_snapshot()
-    except SlurmQueryError as exc:
-        log.warning("admission: cannot read the queue (%s); releasing nothing", exc)
-        return AdmissionReport()
-    # Only the kernel's own LAUNCH jobs are ever released or cancelled here,
-    # attributed by JOB ID through each record's launch ids (a candidate park's
-    # afterany also carries the gate's evals, which are never launches). Names
-    # are never parsed: they are cut to 60 characters at submission, and
-    # `squeue --me` lists every job of the Unix user, ours or not. A held job
-    # no record claims is left exactly as it is.
-    from outerloop.attempt import _stage_launch_job_ids
-
-    owner_state: dict[str, str] = {}
-    for record in list_runs(root):
-        for jid in _stage_launch_job_ids(record):
-            owner_state[jid] = record.state
-    held: list[dict[str, str]] = []
-    in_use = 0
-    at_cap = False
-    dropped: list[str] = []
-    for row in rows:
-        state, reason, jid = row.get("state", ""), row.get("reason", ""), row.get("id", "")
-        gpus = gpus_in_gres(row.get("gres", ""))
-        owner = owner_state.get(jid)
-        if is_pending(state) and reason.startswith("JobHeldUser"):
-            if owner is None:
-                continue  # not ours, or not a launch: never touched
-            if owner != WAITING:
-                # the run ended (PR landed, abandoned, stuck) before its
-                # launch ever ran: nothing will read the result
-                if not dry_run:
-                    with contextlib.suppress(Exception):
-                        compute.cancel(jid)
-                dropped.append(jid)
-                continue
-            held.append(row)
-            continue
-        # every GPU job that is not finished counts against the cap, including
-        # one still COMPLETING: Slurm holds its allocation until it exits
-        if gpus and not is_terminal(state) and state != GONE:
-            in_use += gpus
-            if is_pending(state) and owner is not None and _cap_reason(reason):
-                at_cap = True
-    held.sort(key=lambda r: int(r["id"]) if r["id"].isdigit() else 0)
-    released: list[str] = []
-    if spec.max_launch_gpus <= 0:
-        # admission switched off after these were submitted held: let every
-        # claimed launch go, or they would wait as JobHeldUser forever
-        for row in held:
-            if not dry_run:
-                compute.release(row["id"])
-            released.append(row["id"])
-    elif at_cap:
-        log.info(
-            "admission: a released launch waits on a per-user cap; %d held launch(es) stay held",
-            len(held),
-        )
-    else:
-        for row in held:
-            gpus = gpus_in_gres(row.get("gres", ""))
-            if in_use + gpus > spec.max_launch_gpus:
-                break
-            if not dry_run:
-                compute.release(row["id"])
-            released.append(row["id"])
-            in_use += gpus
-    if released or dropped:
-        log.info(
-            "admission: released %s; dropped %s; %d still held; %d/%d GPUs in use",
-            ",".join(released) or "-",
-            ",".join(dropped) or "-",
-            len(held) - len(released),
-            in_use,
-            spec.max_launch_gpus,
-        )
-    return AdmissionReport(
-        released=tuple(released),
-        dropped=tuple(dropped),
-        held=len(held) - len(released),
-        gpus_in_use=in_use,
-    )
+    status = warm(root, target, github, github.default_branch(target))
+    if status != "unchanged":
+        log.info("eval cache for %s: %s", target, status)
+    return status
 
 
 def service_syncs(root: Path, spec: Any, now: float) -> None:
@@ -2041,7 +1985,7 @@ def service_syncs(root: Path, spec: Any, now: float) -> None:
     are written — safe next to the session's local git use. Best-effort per
     run; a failure leaves the request standing for the next cycle."""
     from outerloop.appauth import resolve_bot_auth
-    from outerloop.attempt import _target_clone_url
+    from outerloop.attempt import target_clone_url
     from outerloop.github import Workspace
     from outerloop.syscall import mark_synced, sync_requested
 
@@ -2062,7 +2006,7 @@ def service_syncs(root: Path, spec: Any, now: float) -> None:
                     if (spec.pat_file or spec.github_app_file)
                     else None
                 ),
-                url=_target_clone_url(record.target),
+                url=target_clone_url(record.target),
             )
             ws.fetch_origin()
             mark_synced(workspace, requested_at)
@@ -2271,16 +2215,6 @@ def _pending_path(root: Path, target: str, agent: str = "") -> Path:
     return root / "pending" / (target.replace("/", "__") + suffix + ".json")
 
 
-def read_pending(root: Path, target: str, agent: str = "") -> dict[str, Any] | None:
-    """The submit-time marker for a climb whose run record may not exist yet."""
-    path = _pending_path(root, target, agent)
-    try:
-        data = json.loads(path.read_text())
-    except (OSError, ValueError):
-        return None
-    return data if isinstance(data, dict) and "submitted_at" in data else None
-
-
 def list_pendings(root: Path, target: str) -> list[tuple[str, dict[str, Any]]]:
     """(agent, marker) for every live pending marker of `target` — one per
     WIDTH slot, plus the legacy un-suffixed marker from a pre-width deploy
@@ -3119,21 +3053,6 @@ def _wake_dispatcher_from_env(
     return JobWakeDispatcher(compute, followup_spec, now), True
 
 
-def max_launch_gpus_from_env() -> int:
-    """OUTERLOOP_MAX_LAUNCH_GPUS: the per-user GPU cap launch admission keeps
-    the fleet under; unset, empty or 0 = admission off. Read by the tick (to
-    release) and by the attempt (to submit held), so the two agree."""
-    raw = os.environ.get("OUTERLOOP_MAX_LAUNCH_GPUS", "").strip()
-    if not raw:
-        return 0
-    try:
-        value = int(raw)
-    except ValueError:
-        log.warning("OUTERLOOP_MAX_LAUNCH_GPUS=%r is not an integer; admission off", raw)
-        return 0
-    return max(value, 0)
-
-
 def _max_job_minutes_from_env() -> int:
     """OUTERLOOP_MAX_JOB_MINUTES, clamped into what the code can honor:
     at least the climb-job floor (an operator on a short-MaxTime partition
@@ -3240,16 +3159,9 @@ def _followup_spec_from_env(root: Path) -> tuple[Any, FollowupSpec | None]:
     # association and the partition to Slurm's defaults, as `start` already
     # does for the resident. Local compute has no placement at all.
     target = os.environ.get("OUTERLOOP_TARGET", "")
-    if not os.environ.get("OUTERLOOP_BOT_LOGIN", "").strip():
-        # the default is the lab's bot account; under any other credential
-        # the kernel would not recognize its own comments and PRs (#298)
-        from outerloop.github import DEFAULT_BOT_LOGIN
-
-        log.warning(
-            "OUTERLOOP_BOT_LOGIN is not set; posting as the default %r. Set it to the "
-            "login the kernel posts as (init records it) unless that is your account.",
-            DEFAULT_BOT_LOGIN,
-        )
+    # no default identity (#298): every own-comment and own-PR filter keys on
+    # this login, and a wrong one is worse than none
+    bot_login = os.environ.get("OUTERLOOP_BOT_LOGIN", "").strip()
     image_ok = Path(image).is_file()
     panel = os.environ.get("OUTERLOOP_PANEL", "verify,review")
     if not image_ok and local_mode():
@@ -3276,7 +3188,7 @@ def _followup_spec_from_env(root: Path) -> tuple[Any, FollowupSpec | None]:
         # the jobs must not inherit a path to an image that is not there
         os.environ.pop("OUTERLOOP_IMAGE", None)
         image, image_ok = "", True
-    if (pat_file or app_file) and home and target and image_ok:
+    if (pat_file or app_file) and home and target and bot_login and image_ok:
         from outerloop.appauth import resolve_bot_auth
         from outerloop.github import GitHubClient
 
@@ -3298,7 +3210,6 @@ def _followup_spec_from_env(root: Path) -> tuple[Any, FollowupSpec | None]:
                 gpu_partition=os.environ.get("OUTERLOOP_GPU_PARTITION", ""),
                 gpu_account=os.environ.get("OUTERLOOP_GPU_ACCOUNT", ""),
                 max_job_minutes=_max_job_minutes_from_env(),
-                max_launch_gpus=max_launch_gpus_from_env(),
             )
             return github, followup_spec
         except Exception as exc:
@@ -3310,6 +3221,7 @@ def _followup_spec_from_env(root: Path) -> tuple[Any, FollowupSpec | None]:
             ("OUTERLOOP_PAT_FILE or _GITHUB_APP_FILE", pat_file or app_file),
             ("OUTERLOOP_HOME", home),
             ("OUTERLOOP_TARGET", target),
+            ("OUTERLOOP_BOT_LOGIN", bot_login),
         ]
         if not value
     ]

outerloop/verify_agent.py

@@ -20,7 +20,7 @@ from outerloop.contract import find_contract
 from outerloop.github import GitHubClient
 from outerloop.harness import Harness, backend_id, budget_exhausted, outage
 from outerloop.posting import EXPECTED_FAILURES, post_round, post_skip_stub
-from outerloop.review_agent import _emit, _pull_request
+from outerloop.review_agent import emit_envelope, pull_request
 from outerloop.role_runner import run_role
 from outerloop.roles import verifier_spec, verify_result_from_role
 from outerloop.rolespec import RoleSpec
@@ -81,19 +81,21 @@ def run_agent_verify(
         # `detail` is already api-key-redacted by the harness (it owns its own
         # secret), so no secret is passed here.
         if emit_path is not None:
-            _emit(emit_path, repo, number, kind="skip-stub", detail=detail, reviewed_by=reviewed_by)
+            emit_envelope(
+                emit_path, repo, number, kind="skip-stub", detail=detail, reviewed_by=reviewed_by
+            )
         else:
             post_skip_stub(client, repo, number, "verification", RuntimeError(detail))
 
     try:
-        pr, pr_data = _pull_request(client, repo, number)
+        pr, pr_data = pull_request(client, repo, number)
         skip = verify_skip_reason(pr, bot_login)
         if skip is not None:
             log.info("skipping verification of %s#%s: %s", repo, number, skip)
             # a clean skip still leaves an envelope so the post job can REQUIRE
             # an artifact — a missing one then always means a broken session
             if emit_path is not None:
-                _emit(emit_path, repo, number, kind="skip-clean", detail=skip)
+                emit_envelope(emit_path, repo, number, kind="skip-clean", detail=skip)
             return None
 
         contract_text = _base_contract(client, repo, pr_data)
@@ -122,11 +124,11 @@ def run_agent_verify(
             elif emit_path is not None:
                 # nothing worth posting, but the post job still needs an
                 # artifact so a MISSING one always means a broken session
-                _emit(emit_path, repo, number, kind="skip-clean", detail=detail)
+                emit_envelope(emit_path, repo, number, kind="skip-clean", detail=detail)
             return None
 
         if emit_path is not None:
-            _emit(
+            emit_envelope(
                 emit_path,
                 repo,
                 number,

outerloop/verify_post_cli.py

@@ -20,7 +20,7 @@ from pathlib import Path
 
 from outerloop.github import EnvTokenProvider, GitHubClient
 from outerloop.posting import EXPECTED_FAILURES, post_round, post_skip_stub
-from outerloop.review_agent import _pull_request
+from outerloop.review_agent import pull_request
 from outerloop.verifier import (
     VERIFY_MARKER,
     format_verify_comment,
@@ -58,7 +58,7 @@ def post_from_file(
         # the write authority re-checks the bot-only rule for EVERY kind: this
         # side of the artifact boundary is the one that must never post on a
         # non-bot PR — a forged envelope is still a post
-        pr, pr_data = _pull_request(client, repo, number)
+        pr, pr_data = pull_request(client, repo, number)
         skip = verify_skip_reason(pr, bot_login)
         if skip is not None:
             log.info("skipping post on %s#%s: %s", repo, number, skip)

outerloop/watcher.py

@@ -0,0 +1,203 @@
+"""The session watcher: a thread beside a live author session that answers its
+questions through the syscall channel in seconds — `queue` (the kernel's jobs
+in the cluster queue, every agent's) and `history` (this run's launches) —
+where the tick would take a cadence. It changes no lifecycle state: it writes
+answer files into the channel and nothing else; submitting, cancelling,
+sealing and parking stay at the sleep boundary (docs/design/session-watcher.md).
+
+Failure never reaches the session: an exception is logged and the request is
+left standing, the tool times out and says so. A watcher that dies leaves the
+session exactly as it is without one."""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from outerloop.climbboard import queue_rows
+from outerloop.launchlog import history, why_by_job
+from outerloop.runstate import run_dir
+from outerloop.syscall import MAX_WHY_CHARS, mark_done, marker_requested, write_channel_json
+
+log = logging.getLogger(__name__)
+
+VERBS = ("queue", "history")
+POLL_S = 2.0
+# one scheduler query per this many seconds however often the marker is
+# rewritten: a session cannot turn the watcher into a squeue loop
+QUERY_GAP_S = 5.0
+MAX_QUEUE_ROWS = 500
+# squeue names a pending array `<id>_[0-15%4]` and a running task `<id>_3`
+_ARRAY_THROTTLE = re.compile(r"_\[[^\]]*%(\d+)\]$")
+# the lane's node states move slowly; one sinfo a minute is plenty
+LANE_GAP_S = 60.0
+# a stopped watcher may still be inside a scheduler query (its own timeout,
+# a minute at most); the attempt waits this long for it, then moves on — the
+# thread is a daemon and writes nothing once stopped
+JOIN_S = 15.0
+
+
+@dataclass
+class WatcherContext:
+    """What the watcher needs to answer: where the channel is, which run it
+    serves, and the compute backend to ask (None = no queue, local mode)."""
+
+    workspace: Path
+    run_root: Path
+    run_id: str
+    target: str
+    agent_id: str
+    compute: Any = None
+    gpu_partition: str = ""
+    poll_s: float = POLL_S
+    query_gap_s: float = QUERY_GAP_S
+    lane_gap_s: float = LANE_GAP_S
+    clock: Callable[[], float] = field(default=time.time)
+
+
+def _kind(name: str) -> str:
+    """A short label for a kernel job that is not a launch."""
+    for key in ("wake", "followup", "eval", "resident", "tick"):
+        if key in name:
+            return key
+    return name
+
+
+class SessionWatcher:
+    """`with SessionWatcher(ctx):` around the harness subprocess. `service()`
+    is one pass, public so the loop is testable without the thread."""
+
+    def __init__(self, ctx: WatcherContext) -> None:
+        self.ctx = ctx
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._queue_cache: dict[str, Any] | None = None
+        self._queue_at = 0.0
+        self._lane_cache: dict[str, Any] | None = None
+        self._lane_at = 0.0
+
+    def __enter__(self) -> SessionWatcher:
+        self._thread = threading.Thread(target=self._loop, name="session-watcher", daemon=True)
+        self._thread.start()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=JOIN_S)
+            if self._thread.is_alive():
+                log.warning("session watcher still inside a scheduler query at session end")
+
+    def _loop(self) -> None:
+        # wait() is False on timeout: poll; True once stopped
+        while not self._stop.wait(self.ctx.poll_s):
+            self.service()
+
+    def service(self) -> None:
+        """Answer every verb whose request marker is newer than its done marker."""
+        for verb in VERBS:
+            if self._stop.is_set():
+                return
+            try:
+                requested = marker_requested(self.ctx.workspace, f"{verb}-request", f"{verb}-done")
+                if requested is None:
+                    continue
+                payload = self.queue_view() if verb == "queue" else self.history_view()
+                if self._stop.is_set():
+                    return  # the session ended meanwhile: nothing is written after it
+                write_channel_json(self.ctx.workspace, f"{verb}.json", payload)
+                mark_done(self.ctx.workspace, f"{verb}-done", requested)
+            except Exception as exc:  # the request stands; the tool times out
+                log.warning("session watcher: %s failed: %s", verb, exc)
+
+    def history_view(self) -> dict[str, Any]:
+        ctx = self.ctx
+        return {
+            "at": ctx.clock(),
+            "run_id": ctx.run_id,
+            "history": history(run_dir(ctx.run_root, ctx.run_id)),
+        }
+
+    def queue_view(self) -> dict[str, Any]:
+        """The kernel's jobs as the board projects them (attributed to agents),
+        each launch labelled with its author's `why`, plus the GPU lane's load.
+        Cached for `query_gap_s` — the rate limit on scheduler queries."""
+        ctx = self.ctx
+        now = ctx.clock()
+        if self._queue_cache is not None and now - self._queue_at < ctx.query_gap_s:
+            return {**self._queue_cache, "at": now, "cached": True}
+        error = ""
+        rows: list[dict[str, Any]] = []
+        try:
+            snapshot = ctx.compute.queue_snapshot() if ctx.compute is not None else []
+            rows = [
+                dict(r) for r in queue_rows(ctx.run_root, ctx.target, snapshot)[:MAX_QUEUE_ROWS]
+            ]
+        except Exception as exc:
+            error = str(exc)[:200]
+        labels: dict[str, dict[str, Any]] = {}
+        for rid in {str(r.get("run_id") or "") for r in rows} - {""}:
+            labels.update(why_by_job(run_dir(ctx.run_root, rid)))
+        for r in rows:
+            rid = str(r.get("run_id") or "")
+            name = str(r.get("name") or "")
+            prefix = f"{rid}-launch-" if rid else ""
+            r["mine"] = bool(rid) and rid == ctx.run_id
+            job_id = str(r.get("id") or "")
+            throttle = _ARRAY_THROTTLE.search(job_id)
+            if throttle:
+                r["concurrency"] = int(throttle.group(1))
+            if prefix and name.startswith(prefix):
+                r["experiment"] = name[len(prefix) :]
+                # the ledger keys the array's id; squeue shows `<id>_<k>` or `<id>_[...]`
+                base = job_id.split("_", 1)[0]
+                label = labels.get(base, {})
+                r["why"] = str(label.get("why", ""))[:MAX_WHY_CHARS]
+                r["kind"] = "launch"
+                # the pace: the pending range says it; once only running tasks
+                # are left, the ledger does (the whole array when unset)
+                array = int(label.get("array") or 1)
+                if "concurrency" not in r and array > 1:
+                    r["concurrency"] = int(label.get("concurrency") or array)
+            else:
+                r["experiment"] = ""
+                r["why"] = ""
+                r["kind"] = _kind(name)
+        view = {
+            "at": now,
+            "run_id": ctx.run_id,
+            "agent": ctx.agent_id,
+            "jobs": rows,
+            "lane": self._lane_load(),
+            "error": error,
+        }
+        self._queue_cache, self._queue_at = view, now
+        return view
+
+    def _lane_load(self) -> dict[str, Any]:
+        """The GPU lane's node states, refreshed once per `lane_gap_s` (a
+        second scheduler query per request would defeat the rate limit). A
+        failed sinfo is reported in the answer, never passed off as a lane
+        with no state."""
+        ctx = self.ctx
+        load = getattr(ctx.compute, "lane_load", None)
+        if load is None or not ctx.gpu_partition:
+            return {}
+        now = ctx.clock()
+        if self._lane_cache is not None and now - self._lane_at < ctx.lane_gap_s:
+            return self._lane_cache
+        try:
+            lane: dict[str, Any] = {
+                "partition": ctx.gpu_partition,
+                "nodes": load(ctx.gpu_partition),
+            }
+        except Exception as exc:
+            lane = {"partition": ctx.gpu_partition, "nodes": {}, "error": str(exc)[:200]}
+        self._lane_cache, self._lane_at = lane, now
+        return lane