runops 2.4.0__tar.gz → 2.5.0__tar.gz

{runops-2.4.0 → runops-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runops
-Version: 2.4.0
+Version: 2.5.0
 Summary: Run ledger and Slurm job submission for HPC simulation projects
 Project-URL: Homepage, https://github.com/Nkzono99/runops
 Project-URL: Documentation, https://github.com/Nkzono99/runops/blob/main/docs/reference.md

{runops-2.4.0 → runops-2.5.0}/SPEC.md

@@ -460,6 +460,22 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 
 ---
 
+### 6.4 進捗
+
+adapter が `progress(run_dir)` を持つとき、`sync` は running の run と、queue を離れた
+直後の run について呼び、`{done, total, unit, start}` を受け取る。`done` は今の到達点、
+`total` は目標（不明なら省略）、`unit` は数える単位（`batch`、`step` など）、`start` は
+この attempt を始めた地点（resume した run の再開点。新規なら 0）。
+
+- 観測は `submit/progress.<job_id>.jsonl` に `{at, done}` として追記する（attempt ごと、
+  上限 1000 件程度）。queue を離れたときの観測は終了時刻で記録し、終了後の待ち時間を速度に含めない。
+- 要約を `[[job.attempts]].progress` に置く: `done`、`total`、`unit`、`start`、`fraction`、
+  `rate_recent_per_hour`（直近 10 分）、`rate_attempt_per_hour`（program 開始から。起点は
+  `start`）、`eta_hours`（running のみ）。program 開始時刻は job.sh が stdout に出す
+  `runops: start` 行から取り、`started_at` に入れる。
+- `status` / `list` は要約だけを読む（file を開かない）。read-only command は観測を足さない。
+- 解析は adapter が行い、runops は保存と表示だけを持つ（§1.2 #4）。
+
 ## 7. CLI
 
 ### 7.1 共通規則
@@ -502,7 +518,7 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 | `runo case new NAME --simulator SIM [--from CASE]` | case をスキャフォールド。adapter の `case_template()` を展開 |
 | `runo case list` | case 一覧 |
 | `runo new CASE [--why TEXT] [--label L] [--set k=v]... [--job k=v]... [--tag T]... [--scratch] [--dest DIR] [--submit] [--created-by WHO] [--json]` | 単発 run を作る |
-| `runo new --from RUN [--why] [--set k=v]... [--job k=v]... [--job-from-case] [--continue] [--submit]` | 既存 run の params と `[job]` から派生 run を作る（§5）。`--continue` は adapter が `extend_inputs()` を実装する場合のみ有効（§8.1） |
+| `runo new --from RUN [--why] [--set k=v]... [--job k=v]... [--job-from-case] [--continue] [--submit]` | 既存 run の params と `[job]` から派生 run を作る（§5）。置き場所の既定は元 run と同じ directory（元 run が archive / scratch なら `runs/<case>/`）。`--continue` は adapter が `extend_inputs()` を実装する場合のみ有効（§8.1） |
 | `runo sweep CASE --set k=v1,v2,... [--set ...] [--names KEY=n1,n2,...]... [--job k=v]... [--label L] [--dest DIR] [--why TEXT] [--apply] [--submit] [--limit N] [--json]` | 直積の候補を表示する。`--apply` で生成。`--submit` は `--apply` と同時のみ有効 |
 | `runo submit RUN... [--partition P] [--qos Q] [--afterok JOBID] [-y]` | job.sh を生成して sbatch。`created` 以外は拒否 |
 | `runo submit --all [DIR] [-y]` | DIR 配下の `created` run をすべて投入。件数と概算 core-hours を表示して確認 |
@@ -621,6 +637,7 @@ class SimulatorAdapter(ABC):
     def agent_context_dir(self) -> Path | None: return None      # §8.2
     def configure(self, sim_config: dict) -> None: ...           # runops.toml の [simulators.X] を受け取る
     def job_prelude(self, run_dir: Path) -> list[str]: return [] # job.sh で実行直前に置く shell 行
+    def progress(self, run_dir: Path) -> dict | None: return None  # §6.4。{done, total, unit, start}
 ```
 
 - job.sh は run_dir へ `cd` してから実行する（v1 と同じ。v1 adapter の path 規約
@@ -675,8 +692,9 @@ runops は `init` と `update` で次を行う。
    （例: `mpiemses3d-input-review`）。`runops-` で始まる名前は予約されており展開しない。
 2. `references/` を `.agents/skills/<adapter>-references/` にコピーし、
    `SKILL.md` が無ければ reference 一覧を列挙した `SKILL.md` を生成する。
-   展開した skill の `../../references/`（package 内の配置での参照）は
-   `../<adapter>-references/` に書き換える。
+   `docs/` があれば同じく `.agents/skills/<adapter>-docs/` に置く。展開した skill の
+   `../../references/`、`../../docs/`（package 内の配置での参照）は `../<adapter>-references/`、
+   `../<adapter>-docs/` に書き換える。
 3. 展開先には `.managed-by-runops` marker を置く。marker のある directory は
    `update` 時に **無条件で上書き** する。marker の無い同名 directory は触らず warning。
 4. `.runops/skills.lock` に adapter 名、package version、展開した directory、content hash を記録する。
@@ -981,5 +999,6 @@ v2 の文書は次の 4 ファイルだけにする。
 | 置き換えた系列の整理（2026-10-21） | `archive` が DIR（系列）を受け、`--superseded-by` で置き換え先を manifest に記録する。新しい command と tidy の種別は足さない。skill は新系列を作ったら旧系列の要否を確かめ、不要なら archive して現用系列・archive 先・件数を報告する | 修正版を作った後に旧系列が作業領域に残り、毎回ユーザーが整理を頼んでいた。`parent_run` だけでは比較用の派生と置き換えを区別できないので、置き換えは明示操作で記録する。旧 `archive` は 1 件ずつ検査していて、途中の running run で一部だけ移動していた（#113） |
 | 生成ハーネスの書き方（2026-10-21） | AGENTS.md の Rules を「作業の進め方」5 項目に絞り、各項目を「何をするか」と短い理由で書く。skill は手順に専念し、AGENTS.md の方針（manifest を手で編集しない等）を繰り返さない | #112・#113 で規則が増え、禁止形（never / do not）が並んでいた。現行の Claude の prompting 指針は、しないことより何をするかを、理由と共に書くことを勧め、強い禁止語は過剰反応を招くとしている |
 | 複数 run の mv / archive（2026-10-22） | 1 回の `run.lock` の下で全対象を読み直して検査し、通ってから移す。途中の filesystem error では移し終えた run id を示して止まる | `mv A B C --dest X` は 1 件ずつ検査して移していたので、途中の submitted run で一部だけ移動していた。archive は表示の後で lock を取り直していて、その間に再投入された run で同じことが起き得た |
+| 進捗と系列配置 2.5.0（2026-10-23） | adapter に任意の `progress()`、`sync` が時刻付き観測を保存し速度・残り時間を要約（§6.4）。`new --from` の既定置き場所を元 run と同じ directory に。agent context の `docs/` も展開 | 速度比較のために agent が時刻付き batch 観測を手で保存し、再開点や終了後の待ちを毎回補正していた（4 回）。継続世代が case 直下に並び、同じ計算の系列を見分けにくかった。skill が package の `docs/` を参照していたが展開されていなかった。進捗の解析は simulator 固有なので adapter が持ち、runops は保存と表示だけにする |
 | FEEDBACK 棚卸し 2.4.0（2026-10-23） | `--job k=v` と `new --from` の `[job]` 継承、created の archive / restore、archived scratch を期限削除しない、展開 skill の references 参照の書き換えと `doctor` のリンク検査、adapter warning への版の併記、生成 AGENTS.md に解析環境の置き場所 | hub の FEEDBACK で、資源変更のための case 編集（3 回）、置換済み draft を archive できず helper で迂回（2 回）、保管目的の archive が期限削除される、skill から reference に辿れない、新版の正規キーが誤記に見える、解析依存の置き場所が project ごとに違う、が記録された。いずれも既存 command の拡張で、command 数は増やさない |
 | 使い方ガイド | `docs/guide.md` を追加し、文書を 4 ファイルにする（§13.3） | README の依頼例の表と command 一覧の間を埋める、場面ごとの流れ（case と run の分け方、smoke から本計算、状態の決まり方、整理）の置き場所が無かった |

{runops-2.4.0 → runops-2.5.0}/docs/adapter.md

@@ -49,6 +49,7 @@ class Adapter:
 | `keep_patterns() -> list[str]` | `tidy --purge-work` で残す glob |
 | `extend_inputs(src_run, run_dir, params) -> list[str]` | `runo new --from RUN --continue` の restart 設定 |
 | `agent_context_dir() -> Path | None` | 同梱 skill と reference の場所 |
+| `progress(run_dir) -> dict | None` | 進捗 `{"done", "total", "unit", "start"}`。`runo sync` が時刻付きで保存し、速度と残り時間を出す |
 
 `runtime` は `executable`、`package_version`、`exe_hash`、`git_commit`、`git_dirty`、
 `env`、`resolver_mode`、`build_dir` を持ちます。
@@ -76,14 +77,15 @@ project の `adapters/mysim.py` に `Adapter` という名前で置けば使え
 <dir>/
   skills/<skill-name>/SKILL.md
   references/*.md
+  docs/*.md          # 任意。references と同じく展開する
 ```
 
 `runo init` と `runo update` は `skills/*` を project の `.agents/skills/` と
 `.claude/skills/` に同名でコピーし、`references/` を `<adapter>-references` として置きます。
 skill 名は package 側で名前空間を付けてください（例: `mysim-input-review`）。
 `runops-` で始まる名前は予約されています。skill から reference へは
-`../<adapter>-references/X.md` と書いてください。package 内の配置どおりの
-`../../references/X.md` は展開時にこの形へ書き換えます。`runo doctor` は展開済み skill の
+`../<adapter>-references/X.md`（`docs/` なら `../<adapter>-docs/X.md`）と書いてください。
+package 内の配置どおりの `../../references/X.md`、`../../docs/X.md` は展開時にこの形へ書き換えます。`runo doctor` は展開済み skill の
 相対リンク切れを報告します。展開した directory には
 `.managed-by-runops` が置かれ、更新時に上書きされます。利用者が作った同名 directory は
 上書きしません。

{runops-2.4.0 → runops-2.5.0}/docs/guide.md

@@ -131,6 +131,11 @@ walltime は、同じ case・同じ資源で終わった run の実時間を元
 `runo sync` は、active な run が何件あっても `squeue` と `sacct` を 1 回ずつしか呼びません。
 エージェントには `squeue` を直接叩かせず、`runo sync` を使わせてください。
 
+adapter が進捗に対応していれば（BEACH の batch、MPIEMSES3D の step）、`sync` のたびに時刻付きの
+観測を残し、`runo list` / `status` に `62% 0.198 s/batch eta 3.1h` のように進み具合、直近 10 分の
+速度、残り時間を出します。resume した run は再開点から数え、終わった run は終了時刻までで速度を出すので、
+版を切り替えた前後の比較にそのまま使えます（`--json` の `progress`）。
+
 ### 状態の決まり方
 
 run の状態は `created → submitted → running → completed | failed | cancelled` と進みます。
@@ -180,6 +185,7 @@ project の run だけが対象です。同じアカウントの別 project の
 > R20261015-0003 の続きを 2 倍の step で。
 
 `runo new --from RUN --continue` で、終わった run の出力から再開する run を作ります。
+`--from` で作る run は元 run と同じ directory に置かれるので、同じ計算の継続は 1 つの directory に並びます。
 再開の方法は simulator ごとに違い、adapter が対応している場合だけ使えます
 （現在は MPIEMSES3D が対応し、`SNAPSHOT1` から再開します）。新しい run は元の run を `parent_run` として記録します。
 

{runops-2.4.0 → runops-2.5.0}/docs/reference.md

@@ -110,7 +110,7 @@ runops だけが書きます。手で編集しないでください。主な fie
 | `[path]` | `run_dir`（project 相対）、`archived_from`、`archived_at` |
 | `[origin]` | `case`、`sweep`、`parent_run`、`created_by`、`case_input_hash` |
 | `[simulator]` | `name`、`adapter`、`adapter_source`、`adapter_version`、`executable`、`resolver_mode`、`package_version`、`exe_hash`、`git_commit`、`git_dirty`、`build_dir` |
-| `[job]` | case の `[job]` に加え `job_id`、`attempt`、`submitted_at`、`finished_at`、`last_slurm_state`、`exit_code`、`[[job.attempts]]`（attempt ごとの `job_id`、`started_at`、`exit_code`、`exe_hash`、`elapsed`、`cancel --why` の `cancel_reason`） |
+| `[job]` | case の `[job]` に加え `job_id`、`attempt`、`submitted_at`、`finished_at`、`last_slurm_state`、`exit_code`、`[[job.attempts]]`（attempt ごとの `job_id`、`started_at`、`exit_code`、`exe_hash`、`elapsed`、`cancel --why` の `cancel_reason`、`runo sync` が付ける `progress`（§進捗）） |
 | `[params]` | case の params に `--set` を適用した最終値 |
 | `[variation]` | `changed_keys`、`job_changed_keys`（case の `[job]` と違う key） |
 | `[identity]` | `input_hash` |
@@ -139,7 +139,9 @@ run id は削除後も再利用しません。`--dest` に既存 run の中は
 ## command
 
 `list --json` と `status --json` は、walltime の根拠として `walltime`、最新 attempt の `elapsed`、
-`walltime_used`（elapsed / walltime）、`slurm_state` も返します。表では `TIMEOUT` などを
+`walltime_used`（elapsed / walltime）、`slurm_state` も返します。adapter が `progress()` を持てば
+`progress`（`done`、`total`、`unit`、`fraction`、`rate_recent_per_hour`、`rate_attempt_per_hour`、
+`eta_hours`）も返し、表の `progress` 列に `62% 0.198 s/batch eta 3.1h` と出します。表では `TIMEOUT` などを
 `failed (TIMEOUT)` と示します。
 
 全 command は `--help` で option を確認できます。`RUN` には run id、run directory、
@@ -154,7 +156,7 @@ run id は削除後も再利用しません。`--dest` に既存 run の中は
 | `runo context [--json]` | agent 向けの現在地 |
 | `runo case new NAME [-s SIM] [--from CASE]` / `runo case list` | case の作成と一覧 |
 | `runo new CASE [--why] [--label] [--set k=v]... [--job k=v]... [--tag] [--scratch] [--dest DIR] [--submit] [--json]` | run を 1 つ作る。`--job` はこの run の `[job]` の値 |
-| `runo new --from RUN [--set k=v]... [--job k=v]... [--job-from-case] [--continue]` | 既存 run の params と `[job]` から派生（`--job-from-case` で `[job]` は case から）。`--continue` は adapter の restart 対応が必要 |
+| `runo new --from RUN [--set k=v]... [--job k=v]... [--job-from-case] [--continue]` | 既存 run の params と `[job]` から派生（`--job-from-case` で `[job]` は case から）。置き場所の既定は元 run と同じ directory。`--continue` は adapter の restart 対応が必要 |
 | `runo sweep CASE --set k=v1,v2 ... [--names k=n1,n2...] [--job k=v]... [--label] [--dest DIR] [--limit N] [--apply] [--submit] [--json]` | 直積の候補表示。`--apply` で作成。`--names` は各値の短い label、`--dest` は sweep directory の親 |
 | `runo submit RUN... [-p P] [--qos Q] [--afterok JOB]` / `runo submit --all [DIR] [-y]` | job.sh を生成して sbatch |
 | `runo cancel RUN... [--why TEXT] [-y]` / `runo retry RUN [--submit] [-y]` | scancel（`--why` は note に残る）/ failed・cancelled を created に戻す（理由付きで cancel された run は確認を取る） |

{runops-2.4.0 → runops-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runops"
-version = "2.4.0"
+version = "2.5.0"
 description = "Run ledger and Slurm job submission for HPC simulation projects"
 readme = "README.md"
 license = "Apache-2.0"

{runops-2.4.0 → runops-2.5.0}/src/runops/__init__.py

@@ -1,3 +1,3 @@
 """runops: run ledger and Slurm job submission for HPC simulation projects."""
 
-__version__ = "2.4.0"
+__version__ = "2.5.0"

{runops-2.4.0 → runops-2.5.0}/src/runops/cli.py

@@ -592,9 +592,20 @@ def retry(
 
 def _status_table(project: Project, manifests: list[Manifest]) -> Table:
     from runops.ops.listing import relative_age
+    from runops.ops.progress import format_progress
 
     table = Table(
-        "id", "status", "label", "case", "sweep", "created", "elapsed", "note", "why", box=None
+        "id",
+        "status",
+        "label",
+        "case",
+        "sweep",
+        "created",
+        "elapsed",
+        "progress",
+        "note",
+        "why",
+        box=None,
     )
     for m in manifests:
         s = m.to_summary(project.root)
@@ -625,6 +636,7 @@ def _status_table(project: Project, manifests: list[Manifest]) -> Table:
             s["sweep"],
             relative_age(s["created_at"]),
             elapsed,
+            format_progress(s["progress"]),
             s["last_note"][:60],
             s["why"][:60],
         )

{runops-2.4.0 → runops-2.5.0}/src/runops/manifest.py

@@ -220,8 +220,16 @@ class Manifest:
             "input_hash": str(self.section("identity").get("input_hash", "")),
             # Walltime evidence for the next run: elapsed of the latest attempt.
             **self.timing(),
+            "progress": self.progress,
         }
 
+    @property
+    def progress(self) -> dict[str, Any] | None:
+        """Progress of the latest attempt as `runo sync` last saw it (adapter ``progress()``)."""
+        attempts = self.job.get("attempts") or []
+        value = attempts[-1].get("progress") if attempts else None
+        return dict(value) if isinstance(value, dict) else None
+
     def timing(self) -> dict[str, Any]:
         """Walltime, latest attempt elapsed, the fraction used, and the last Slurm state."""
         walltime = str(self.job.get("walltime", ""))

{runops-2.4.0 → runops-2.5.0}/src/runops/ops/create.py

@@ -26,7 +26,7 @@ from runops.errors import RunError, UsageError
 from runops.manifest import MANIFEST_FILE, SCHEMA_VERSION, Manifest
 from runops.ops.common import SimContext, resolve_dest, sim_context
 from runops.ops.submit import write_job_for
-from runops.project import SCRATCH_DIR, Project
+from runops.project import ARCHIVE_DIR, SCRATCH_DIR, Project
 from runops.runtime import resolve_runtime
 from runops.util import hash_tree, move_noreplace, now_iso, parse_value
 
@@ -190,6 +190,18 @@ def _dest_parent(project: Project, case: Case, dest: str, scratch: bool) -> Path
     return resolve_dest(project, dest)
 
 
+def _beside(project: Project, source: Manifest) -> Path | None:
+    """The source run's directory under ``runs/``, unless it is archived or scratch."""
+    parent = source.run_dir.resolve().parent
+    runs = project.runs_dir.resolve()
+    if parent != runs and runs not in parent.parents:
+        return None
+    first = parent.relative_to(runs).parts[:1]
+    if first and first[0] in (ARCHIVE_DIR, SCRATCH_DIR):
+        return None
+    return parent
+
+
 def create_run(project: Project, request: CreateRequest) -> CreateResult:
     """Create one run from a case, or derived from another run (``--from``)."""
     source: Manifest | None = None
@@ -226,6 +238,10 @@ def create_run(project: Project, request: CreateRequest) -> CreateResult:
         job = dict(case.job)
     job.update(request.job)
     parent = _dest_parent(project, case, request.dest, request.scratch)
+    if source is not None and not request.dest and not request.scratch:
+        # A derived or continued run sits beside its source, so one series (e.g. the
+        # restarts of one calculation) stays in one directory.
+        parent = _beside(project, source) or parent
     spec = RunSpec(
         params=params,
         changed=changed,

runops-2.5.0/src/runops/ops/progress.py

@@ -0,0 +1,197 @@
+"""Progress samples from the adapter's optional ``progress()`` hook (SPEC §6.4, §8.1).
+
+``runo sync`` asks the adapter how far each active run is (``done`` of ``total`` in some
+``unit``) and appends a timestamped sample to ``submit/progress.<job_id>.jsonl``. From the
+samples it derives, per attempt, the recent rate, the rate since the program started
+(counting from the adapter's ``start``, e.g. the batch a resumed run began at) and the
+remaining time, and keeps that summary in ``[[job.attempts]].progress`` so ``status`` and
+``list`` show it without reading files.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from runops.adapters.registry import optional
+from runops.errors import RunopsError
+from runops.manifest import Manifest
+from runops.ops.common import run_sim_context
+from runops.project import Project
+from runops.util import parse_iso
+
+SAMPLES_KEPT = 1000  # per attempt; older samples are dropped when the file doubles
+RECENT_WINDOW = timedelta(minutes=10)
+_START_MARK = "runops: start "
+
+
+def samples_path(run_dir: Path, job_id: str) -> Path:
+    return run_dir / "submit" / f"progress.{job_id}.jsonl"
+
+
+def read_progress(project: Project, manifest: Manifest) -> dict[str, Any] | None:
+    """The adapter's ``progress(run_dir)`` as ``{done, total, unit, start}``, or ``None``."""
+    try:
+        ctx = run_sim_context(project, manifest)
+        raw = optional(ctx.adapter, "progress", None, manifest.run_dir)
+    except (RunopsError, OSError, ValueError):
+        return None
+    if not isinstance(raw, dict) or not isinstance(raw.get("done"), (int, float)):
+        return None
+    total = raw.get("total")
+    start = raw.get("start")
+    return {
+        "done": raw["done"],
+        "total": total if isinstance(total, (int, float)) and total > 0 else None,
+        "unit": str(raw.get("unit") or "step"),
+        "start": start if isinstance(start, (int, float)) else None,
+    }
+
+
+def record_progress(
+    project: Project, manifest: Manifest, *, at: datetime, final: bool = False
+) -> None:
+    """Append one sample for the latest attempt and refresh its summary in *manifest*.
+
+    Call under ``run.lock``; the caller saves the manifest. *final* marks the sample
+    taken when the run left the queue; *at* is then its finish time, so the rate does
+    not include the time after the job ended.
+    """
+    attempts = manifest.job.get("attempts") or []
+    if not attempts or not manifest.job_id:
+        return
+    current = read_progress(project, manifest)
+    if current is None:
+        return
+    path = samples_path(manifest.run_dir, manifest.job_id)
+    samples = _read_samples(path)
+    samples.append({"at": at.isoformat(timespec="seconds"), "done": current["done"]})
+    _write_samples(path, samples)
+    attempt = attempts[-1]
+    if not attempt.get("started_at"):
+        started = program_start(manifest)
+        if started:
+            attempt["started_at"] = started
+    attempt["progress"] = summarize(
+        samples,
+        total=current["total"],
+        unit=current["unit"],
+        start=current["start"],
+        started_at=parse_iso(str(attempt.get("started_at", ""))),
+        final=final,
+    )
+
+
+def summarize(
+    samples: list[dict[str, Any]],
+    *,
+    total: float | None,
+    unit: str,
+    start: float | None,
+    started_at: datetime | None,
+    final: bool = False,
+) -> dict[str, Any]:
+    points = [(t, float(s["done"])) for s in samples if (t := parse_iso(str(s.get("at", ""))))]
+    last_at, done = points[-1]
+    raw_done = samples[-1]["done"]
+    # Origin for the attempt's average: the program start and the adapter's start value
+    # (a resumed run starts at its checkpoint, not at 0); else the first sample.
+    if started_at is not None and start is not None and started_at <= last_at:
+        origin = (started_at, float(start))
+    else:
+        origin = points[0]
+    earlier = [p for p in points[:-1] if p[0] <= last_at - RECENT_WINDOW]
+    reference = earlier[-1] if earlier else (points[0] if len(points) > 1 else origin)
+    rate_attempt = _rate(origin, points[-1])
+    rate_recent = _rate(reference, points[-1]) or rate_attempt
+    summary: dict[str, Any] = {
+        "done": raw_done,
+        "total": total,
+        "unit": unit,
+        "at": last_at.isoformat(timespec="seconds"),
+        "fraction": round(done / total, 4) if total else None,
+        "rate_recent_per_hour": _round(rate_recent),
+        "rate_attempt_per_hour": _round(rate_attempt),
+        "eta_hours": None,
+    }
+    if start is not None:
+        summary["start"] = start
+    if not final and total and rate_recent:
+        summary["eta_hours"] = round(max(total - done, 0.0) / rate_recent, 2)
+    # TOML has no null: leave unknown values out.
+    return {k: v for k, v in summary.items() if v is not None}
+
+
+def program_start(manifest: Manifest) -> str:
+    """When the program of the latest job started: job.sh prints it in stdout."""
+    from runops.ops.sync import log_paths
+
+    stdout, _ = log_paths(manifest)
+    if stdout is None:
+        return ""
+    try:
+        with stdout.open("rb") as handle:
+            head = handle.read(8192).decode("utf-8", errors="replace")
+    except OSError:
+        return ""
+    for line in head.splitlines():
+        if line.startswith(_START_MARK):
+            stamp = line[len(_START_MARK) :].split()[0]
+            return stamp if parse_iso(stamp) else ""
+    return ""
+
+
+def format_progress(progress: dict[str, Any] | None) -> str:
+    """Short text for tables: ``62% 0.198 s/batch eta 3.1h``."""
+    if not progress:
+        return ""
+    parts = []
+    if progress.get("fraction") is not None:
+        parts.append(f"{progress['fraction']:.0%}")
+    else:
+        parts.append(f"{progress['done']} {progress['unit']}")
+    rate = progress.get("rate_recent_per_hour")
+    if rate:
+        parts.append(f"{3600 / rate:.3g} s/{progress['unit']}")
+    if progress.get("eta_hours") is not None:
+        parts.append(f"eta {progress['eta_hours']:.1f}h")
+    return " ".join(parts)
+
+
+def _rate(a: tuple[datetime, float], b: tuple[datetime, float]) -> float | None:
+    hours = (b[0] - a[0]).total_seconds() / 3600
+    if hours <= 0 or b[1] < a[1]:
+        return None
+    return (b[1] - a[1]) / hours
+
+
+def _round(value: float | None) -> float | None:
+    return float(f"{value:.4g}") if value else None
+
+
+def _read_samples(path: Path) -> list[dict[str, Any]]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return []
+    out = []
+    for line in lines:
+        try:
+            item = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(item, dict) and "at" in item and "done" in item:
+            out.append(item)
+    return out
+
+
+def _write_samples(path: Path, samples: list[dict[str, Any]]) -> None:
+    if len(samples) > 2 * SAMPLES_KEPT:
+        samples = samples[-SAMPLES_KEPT:]
+        path.write_text("".join(json.dumps(s) + "\n" for s in samples), encoding="utf-8")
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(samples[-1]) + "\n")

{runops-2.4.0 → runops-2.5.0}/src/runops/ops/skills.py

@@ -69,8 +69,9 @@ def adapter_sources(project: Project, warnings: list[str]) -> list[SkillSource]:
                     )
                     continue
                 skills[path.name] = path  # the package owns its skill namespace
-        if (directory / "references").is_dir():
-            skills[f"{sim.adapter}-references"] = directory / "references"
+        for folder in _DOC_FOLDERS:
+            if (directory / folder).is_dir():
+                skills[f"{sim.adapter}-{folder}"] = directory / folder
         version = ctx.resolved.version or "local"
         sources.append(SkillSource(sim.adapter, version, skills))
     return sources
@@ -104,8 +105,8 @@ def deploy(project: Project, sources: list[SkillSource]) -> DeployReport:
                 shutil.copytree(src, target)
                 if not (target / "SKILL.md").is_file():
                     _write_reference_index(target, source.source)
-                elif f"{source.source}-references" in source.skills:
-                    _point_at_deployed_references(target, source.source)
+                else:
+                    _point_at_deployed_documents(target, source)
                 (target / MARKER).write_text(
                     f'source = "{source.source}"\nversion = "{source.version}"\n',
                     encoding="utf-8",
@@ -160,18 +161,27 @@ def _marker_source(marker: Path) -> str:
         return ""
 
 
-# A package skill sits in <agent_context>/skills/<name>/ and often reaches its documents as
-# ../../references/; once deployed, the documents live in the sibling <adapter>-references/.
-_PACKAGE_REFERENCES = "../../references/"
+# Document folders an agent context may hold beside skills/. Each is deployed as the
+# skill directory <adapter>-<folder>/ (with a generated SKILL.md index).
+_DOC_FOLDERS = ("references", "docs")
 
 
-def _point_at_deployed_references(target: Path, source: str) -> None:
+def _point_at_deployed_documents(target: Path, source: SkillSource) -> None:
+    """Rewrite ../../<folder>/ (the package layout) to ../<adapter>-<folder>/ (deployed)."""
+    moves = {
+        f"../../{folder}/": f"../{source.source}-{folder}/"
+        for folder in _DOC_FOLDERS
+        if f"{source.source}-{folder}" in source.skills
+    }
+    if not moves:
+        return
     for md in target.rglob("*.md"):
         text = md.read_text(encoding="utf-8")
-        if _PACKAGE_REFERENCES in text:
-            md.write_text(
-                text.replace(_PACKAGE_REFERENCES, f"../{source}-references/"), encoding="utf-8"
-            )
+        new = text
+        for old, replacement in moves.items():
+            new = new.replace(old, replacement)
+        if new != text:
+            md.write_text(new, encoding="utf-8")
 
 
 _LINK = re.compile(r"\]\(([^)\s]+)\)|`(\.\.?/[^`\s]+)`")
@@ -201,14 +211,15 @@ def broken_skill_links(project: Project) -> dict[str, list[str]]:
 
 def _write_reference_index(target: Path, source: str) -> None:
     files = sorted(p.relative_to(target).as_posix() for p in target.rglob("*") if p.is_file())
+    kind = target.name.removeprefix(f"{source}-")  # references | docs
     lines = [
         "---",
         f"name: {target.name}",
-        f"description: Reference documents for the {source} simulator. "
+        f"description: {kind.capitalize()} documents for the {source} simulator. "
         "Read the file that matches the question.",
         "---",
         "",
-        f"# {source} references",
+        f"# {source} {kind}",
         "",
         *[f"- [{name}]({name})" for name in files],
         "",

{runops-2.4.0 → runops-2.5.0}/src/runops/ops/sync.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from datetime import datetime
 from pathlib import Path
 from typing import Any
 
@@ -10,6 +11,7 @@ from runops.errors import RunopsError, UsageError
 from runops.jobgen import exit_record_path
 from runops.manifest import ACTIVE_STATES, Manifest, RunState
 from runops.ops.common import run_sim_context
+from runops.ops.progress import record_progress
 from runops.project import Project
 from runops.slurm import CommandRunner, JobState, default_runner, query, query_many
 from runops.util import format_duration, load_toml, now_iso, parse_duration, parse_iso, tomllib
@@ -112,6 +114,12 @@ def _settle(project: Project, manifest: Manifest, job: JobState | None) -> SyncR
             elapsed = _elapsed(job, record)
             if elapsed:
                 attempts[-1]["elapsed"] = elapsed
+        # The last sample is dated at the finish, so the rate ends where the job did.
+        record_progress(
+            project, manifest, at=parse_iso(now) or datetime.now().astimezone(), final=True
+        )
+    elif new_state == RunState.RUNNING:
+        record_progress(project, manifest, at=datetime.now().astimezone())
     manifest.set_status(new_state)
     manifest.save()
     return SyncResult(manifest.id, before.value, new_state.value, slurm_state, message)

{runops-2.4.0 → runops-2.5.0}/src/runops/skills/runops-check-status/SKILL.md

@@ -9,12 +9,15 @@ description: Check the progress or result of runops runs (sync, list, log, retry
 2. `runo list` shows active and recent runs. `--all`, `--case C`, `--status failed`
    and `--json` narrow or widen the view. Scratch and archived runs are hidden unless
    `--scratch` / `--archived` is given.
-3. `runo status RUN` shows one run; `runo log RUN` and `runo log RUN --err` show the
+3. `runo status RUN` shows one run, with progress, recent speed and time left when the
+   adapter reports progress (`--json` → `progress`; counted from the resume point, ending
+   at the finish). Use it for speed comparisons instead of timing logs by hand.
+   `runo log RUN` and `runo log RUN --err` show the
    tail of the latest job's stdout / stderr (`-n 200` for more, `-f` to follow).
 4. For a failed run, read the stderr log and the adapter summary
    (`runo summarize RUN`). Record the cause with `runo note RUN "..."`.
    `failed (TIMEOUT)` means the walltime ran out: compare `elapsed` with `walltime`
-   and raise the case walltime for the next run.
+   and give the next run more with `--job walltime=...`.
 5. To rerun the same inputs: `runo retry RUN` then `runo submit RUN` after confirming.
    To change inputs, create a new run with `runo new --from RUN --set ...`.
 6. Recovery ("jobs vanished, resubmit them"): `runo sync`, then

{runops-2.4.0 → runops-2.5.0}/src/runops/skills/runops-create-run/SKILL.md

@@ -9,7 +9,7 @@ description: Create simulation runs with runops (runo new / new --from / sweep).
 2. Pick the case. Express the variation with `--set`, not with a new case:
    - one run: `runo new CASE --why "..." --set section.key=value`
    - from an existing run: `runo new --from RUN --why "..." --set key=value`
-     (keeps the source's params and `[job]`; the output lists what differs)
+     (keeps the source's params and `[job]`, and sits beside it; the output lists what differs)
    - continue from a finished run (if the adapter supports it): `runo new --from RUN --continue --why "..."`
    - a product of values: `runo sweep CASE --set a=1,2 --set b=x,y --why "..."`
      shows the points and core-hours without creating anything; add `--apply` to create.

{runops-2.4.0 → runops-2.5.0}/src/runops/skills/runops-reference/SKILL.md

@@ -46,6 +46,6 @@ from the cwd; paths into another project's `runs/` are refused.
 
 `[run]` id, label, status, why, scratch, expires_at, pinned, tags, superseded_by, `[[notes]]`;
 `[origin]` case, sweep, parent_run; `[simulator]` executable and provenance;
-`[job]` resources, job_id, `[[job.attempts]]` (job_id, exit_code, elapsed, cancel_reason); `[params]` final values;
+`[job]` resources, job_id, `[[job.attempts]]` (job_id, exit_code, elapsed, cancel_reason, progress); `[params]` final values;
 `[variation].changed_keys`, `job_changed_keys`. Status: created -> submitted -> running ->
 completed | failed | cancelled; terminal runs can be archived.