runops 2.2.0__tar.gz → 2.3.0__tar.gz

{runops-2.2.0 → runops-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runops
-Version: 2.2.0
+Version: 2.3.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
@@ -74,11 +74,13 @@ runo init
 | 様子を見る | 先週投げた run の状況を見て。失敗していたら原因をノートに残して |
 | 続きを流す | R20261015-0003 の続きを 2 倍の step で |
 | 片付ける | 古い run を整理して。消すものと archive するものを先に見せて |
+| 作り直した旧系列を片付ける | 旧系列は新系列で置き換えたので、対応を記録して archive して |
 | simulator を足す | パッチを当てた ~/BEACH-dev をビルドして、別の simulator として登録して |
 | 更新する | runops と simulator を最新にして |
 | v1 から移る | この project を runops v2 に移行して（`runo migrate-v1` を dry-run で確認してから） |
 
 投入、削除、整理、移行の前には、エージェントが対象と資源量を示して確認を取ります。
+範囲を言わない依頼（「全部再投入して」など）は、エージェントを起動した project の run だけが対象です。
 場面ごとの流れは [使い方ガイド](https://github.com/Nkzono99/runops/blob/main/docs/guide.md) にあります。
 
 ## project の中身

{runops-2.2.0 → runops-2.3.0}/README.md

@@ -43,11 +43,13 @@ runo init
 | 様子を見る | 先週投げた run の状況を見て。失敗していたら原因をノートに残して |
 | 続きを流す | R20261015-0003 の続きを 2 倍の step で |
 | 片付ける | 古い run を整理して。消すものと archive するものを先に見せて |
+| 作り直した旧系列を片付ける | 旧系列は新系列で置き換えたので、対応を記録して archive して |
 | simulator を足す | パッチを当てた ~/BEACH-dev をビルドして、別の simulator として登録して |
 | 更新する | runops と simulator を最新にして |
 | v1 から移る | この project を runops v2 に移行して（`runo migrate-v1` を dry-run で確認してから） |
 
 投入、削除、整理、移行の前には、エージェントが対象と資源量を示して確認を取ります。
+範囲を言わない依頼（「全部再投入して」など）は、エージェントを起動した project の run だけが対象です。
 場面ごとの流れは [使い方ガイド](https://github.com/Nkzono99/runops/blob/main/docs/guide.md) にあります。
 
 ## project の中身

{runops-2.2.0 → runops-2.3.0}/SPEC.md

@@ -325,6 +325,7 @@ scratch = false
 expires_at = ""                   # scratch の場合のみ。ISO 8601
 pinned = false
 tags = ["sheath", "2d"]
+superseded_by = []               # archive --superseded-by で記録した置き換え先の run id
 
 [path]
 run_dir = "runs/flat_surface/R20261015-0003--wc0147_phi45"   # project root 相対。絶対 path は書かない
@@ -378,6 +379,7 @@ slurm_state = "COMPLETED"
 exit_code = 0                     # exit record から
 exe_hash = "sha256:..."           # submit 時点の executable の hash
 elapsed = "15:42:10"              # sacct の Elapsed、無ければ exit record の開始・終了から
+cancel_reason = ""                # cancel --why の理由。retry はこれがあれば確認を取る
 
 [params]
 "tmgrid.nx" = 4000
@@ -461,6 +463,9 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
   見つからなければ exit code 2 でエラー。
 - `RUN` 引数は run id、run directory path、または directory 名の一意な部分文字列を受け付ける。
   複数一致は exit code 2 でエラーにし候補を表示する。
+- path で与える `RUN` と `DIR`（`submit --all`、`list`、`archive`）は、この project の `runs/`
+  配下に限る。別 project の path は exit code 2 で拒否する。run id は project ごとの空間なので、
+  同じ id が別 project にあっても cwd の project の run を指す。
 - 一覧系 command は `--json` を持ち、agent が機械可読に読める。`new` と `sweep --apply` の
   `--json` は作成した run の同じ summary を返す。summary には `params`、`changed_keys`、
   `parent_run`、`exe_hash`、`input_hash` を含め、run 同士の比較に別 command を要らなくする。
@@ -494,8 +499,8 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 | `runo sweep CASE --set k=v1,v2,... [--set ...] [--names KEY=n1,n2,...]... [--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 を表示して確認 |
-| `runo cancel RUN... [-y]` | scancel して sync |
-| `runo retry RUN [--submit]` | `failed`/`cancelled` を `created` に戻す |
+| `runo cancel RUN... [--why TEXT] [-y]` | scancel して sync。`--why` は `cancelled: ...` の note として残す |
+| `runo retry RUN [--submit] [-y]` | `failed`/`cancelled` を `created` に戻す。直近の cancel に `--why` があれば理由を示して確認を取る |
 | `runo status [RUN...] [--json]` | manifest の状態を表示。Slurm を呼ばない |
 | `runo sync [RUN...] [--json]` | squeue/sacct で状態を更新。引数なしは `submitted`/`running` 全件 |
 | `runo log RUN [--err] [-n N] [-f]` | 最新 job の stdout/stderr を表示。`-f` は tail -f |
@@ -504,7 +509,7 @@ created ──submit──▶ submitted ──(slurm)──▶ running ──▶
 | `runo pin RUN [--off] [--reason TEXT]` | `run.pinned` を切り替える。pinned は `list` に常に出て、`tidy` / `delete` の対象外 |
 | `runo summarize RUN... [--force]` | adapter の `summarize()` を呼び `analysis/summary.json` を書く。既存があれば `--force` なしではスキップ |
 | `runo mv RUN... [--dest DIR] [--label L] [--why TEXT]` | run を `runs/` 配下で改名・移動する。id、入力、履歴は変えない（§7.7） |
-| `runo archive RUN... [-y]` / `runo archive --older-than 90d [-y]` | `runs/_archive/<元の相対 path>` に移動して `archived` にする |
+| `runo archive RUN\|DIR... [--superseded-by RUN\|DIR --why TEXT] [-y]` / `runo archive --older-than 90d [-y]` | `runs/_archive/<元の相対 path>` に移動して `archived` にする。移動前に全対象を検査し、指定した RUN が終端でなければ何も動かさない。DIR は配下の run（系列）を指し、終端でない run と pinned を除いて表示する。`--superseded-by` は各 run に置き換え先（`parent_run` がその run の置き換え先 run、無ければ指定した全 run）を `run.superseded_by` に記録し、`--why` を note に残す |
 | `runo restore RUN` | archive 前の場所に戻す。既に何かあれば拒否 |
 | `runo delete RUN... [-y]` | directory を削除。`created`/`failed`/`cancelled`/scratch のみ。`pinned` は拒否 |
 | `runo tidy [--apply] [--only KIND] [--older-than AGE] [--purge-work RUN...] [--json]` | 整理候補を表示する（§7.5）。`--apply` で実行 |
@@ -740,10 +745,12 @@ seal、index を持たない）。
 
 `init` が生成する agent 向けファイルは次だけ。
 
-- `AGENTS.md`: 120 行以内。project 名、simulator、§7.3 の command 表、§9 のノート規約、
-  §5 の「variation は case ではなく run で表現する」規約、
-  「submit 前に対象と資源量を提示して確認を取る」「`manifest.toml` と `input/` を直接
-  編集しない」の 2 つの安全規則、展開済み skill の一覧。
+- `AGENTS.md`: 120 行以内。project 名、simulator、§7.3 の command 表、作業の進め方、
+  §9 のノート規約、展開済み skill の一覧。作業の進め方は次の 5 項目で、それぞれ「何をするか」と
+  短い理由で書く（禁止事項の列挙にしない）。依頼が操作の範囲を決める、submit 前に対象と資源量を
+  示して確認を取る、操作対象は起動した project の run と job、run の変更は `runo` を通す
+  （variation は case ではなく run、§5）、理由を残す（`--why`、`cancel --why`、`--superseded-by`）。
+- skill は手順を書き、AGENTS.md の方針を繰り返さない。
 - harness file は project root にだけ置く。`runs/` や `cases/` 配下には生成しない。
 - `CLAUDE.md`: `@AGENTS.md` の 1 行。
 - `.agents/skills/`、`.claude/skills/`: §8.2、§8.3 の展開結果。
@@ -957,4 +964,7 @@ v2 の文書は次の 4 ファイルだけにする。
 | 整理と命名のしきい値 | `[defaults]` に `tidy_failed_days`、`tidy_archive_days`、`label_max_length` を追加。completed の目安は「`--older-than` の 3 倍」をやめて独立の値に | project ごとに計算期間や命名が違い、エージェントに毎回 option を渡させると揃わない |
 | `runo init` の対話と site の推定 | 端末から引数なしで実行したときだけ site と simulator を尋ねる。site の既定はホスト名（`camphor*`、`laurel*`、`cinnamon*`、`gardenia*` なら `kudpc`）。プリセット名は `kudpc` とし、`camphor` も同じ意味で受け付ける | 人が打つのは `runo init` だけなので、ここで KUDPC 向けの設定を取り違えないようにする。エージェントや CI からの実行（端末でない、`-y`、引数あり）は従来どおり尋ねない |
 | 異常系と同時操作（2026-10-20） | `run.lock` 下で manifest を読み直す、準備の失敗で program を起動しない、adapter を読めなければ purge しない、build cache の key を内容と `build_command` から作る、run の入れ子を禁止、run id を再利用しない（`last_run_id`）、`new --from` で case の変更を警告 | 外部レビューで、二重投入で 1 回目の履歴が消える、準備失敗が completed になる、adapter の故障で保持ファイルが消える、未追跡ファイルの変更で古い binary を使う、削除した id が別の run を指す、を確認した |
+| 操作範囲は起動 project（2026-10-21） | AGENTS.md block と skill に「対象は起動した project の run と job id だけ。アカウント全体の squeue / sacct は診断に見るだけ。自分で別 directory に移らず、生の `sbatch` / `scancel` を使わない」を書く。CLI は別 project の path を拒否する | 範囲を言わない「再投入して」で、エージェントが別 project や runops 管理外のジョブまで再投入した。cwd で project を決める既存の model に、path 引数の抜け道（`submit --all /other/runs` など）があった。他 session が修正のために止めた run を見分けられるよう、`cancel --why` を note に残し、`retry` はその理由を示して確認を取る（#112） |
+| 置き換えた系列の整理（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 指針は、しないことより何をするかを、理由と共に書くことを勧め、強い禁止語は過剰反応を招くとしている |
 | 使い方ガイド | `docs/guide.md` を追加し、文書を 4 ファイルにする（§13.3） | README の依頼例の表と command 一覧の間を埋める、場面ごとの流れ（case と run の分け方、smoke から本計算、状態の決まり方、整理）の置き場所が無かった |

{runops-2.2.0 → runops-2.3.0}/docs/guide.md

@@ -160,11 +160,18 @@ runops が知らない Slurm 状態の job は状態を変えず、`last_slurm_s
 | 原因を調べる | R20261016-0003 が落ちた理由を調べて | `runo log RUN --err`、`runo summarize RUN`、`runo note RUN "..."` |
 | 一時的な障害で、同じ入力で流し直す | 同じ入力でもう一度投げて | `runo retry RUN`、`runo submit RUN` |
 | 入力を直して流し直す | dt を半分にして作り直して | `runo new --from RUN --set ... --why "..."` |
-| 止める | R20261016-0004 を止めて | `runo cancel RUN` |
+| 止める | R20261016-0004 を止めて | `runo cancel RUN`（直すために止めるときは `--why`） |
 
 `retry` は `failed` / `cancelled` の run を `created` に戻し、試行回数を 1 つ増やします。
 `work/` は消しません。
 
+「消えたジョブを再投入して」「全部止めて」のように範囲を言わない依頼は、エージェントを起動した
+project の run だけが対象です。同じアカウントの別 project のジョブや runops 外のジョブは、
+`squeue` に見えていても対象にせず、該当する run が無ければそう伝えます。別 project の run も
+扱いたいときは、その project か run を名指ししてください。
+入力を直すために止めた run は `runo cancel RUN --why "..."` で理由を残すと、別のセッションが
+「消えたジョブ」として再投入しません（`retry` が理由を示して確認を取ります）。
+
 ## 5. 続きを流す
 
 > R20261015-0003 の続きを 2 倍の step で。
@@ -211,6 +218,18 @@ run は消さなくても `runo list` が古いものを隠しますが、direct
 候補を確認したら `runo tidy --apply` で実行します。archive は `runs/_archive/` への移動で、
 run id で引き続き見つかり、`runo restore` で戻せます。
 
+### 置き換えた系列を片付ける
+
+不備を直して新しい系列を作り直すと、エージェントは旧系列がまだ要るかを尋ねます。要らなければ
+
+> 旧系列は不要。新系列で置き換えたと記録して archive して。
+
+で `runo archive runs/<case>/<旧系列> --superseded-by runs/<case>/<新系列> --why "..."` になります。
+系列の directory を渡すと、対象の run を先に表示し、投入中・実行中・作成のみの run と pin した run は
+除きます。各旧 run の `superseded_by` には、その run から `--from` で作った新 run（無ければ新系列の全 run）が
+記録され、理由はノートに残ります。比較用に派生しただけの run は置き換えとは扱わないので、
+旧系列が不要かどうかは毎回確かめます。
+
 論文の図に使う run や基準にする run は pin しておくと、`list` に常に表示され、`tidy` や `delete`
 の対象になりません。
 

{runops-2.2.0 → runops-2.3.0}/docs/reference.md

@@ -6,6 +6,9 @@
 ## runops.toml
 
 project root にあり、`runo` はここを上方向に探して project を特定します。
+command はこの project の `runs/` 配下だけを扱い、別 project の run directory や
+directory を path で渡すとエラーになります。run id は project ごとなので、同じ id が
+別 project にあっても cwd の project の run を指します。
 
 ```toml
 schema = 2
@@ -103,11 +106,11 @@ runops だけが書きます。手で編集しないでください。主な fie
 
 | section | field |
 |---|---|
-| `[run]` | `id`、`label`、`status`、`created_at`、`why`、`scratch`、`expires_at`、`pinned`、`tags`、`status_before_archive` |
+| `[run]` | `id`、`label`、`status`、`created_at`、`why`、`scratch`、`expires_at`、`pinned`、`tags`、`status_before_archive`、`superseded_by`（置き換え先の run id） |
 | `[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`） |
+| `[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`） |
 | `[params]` | case の params に `--set` を適用した最終値 |
 | `[variation]` | `changed_keys` |
 | `[identity]` | `input_hash` |
@@ -154,13 +157,13 @@ run id は削除後も再利用しません。`--dest` に既存 run の中は
 | `runo new --from RUN [--set k=v]... [--continue]` | 既存 run の params から派生。`--continue` は adapter の restart 対応が必要 |
 | `runo sweep CASE --set k=v1,v2 ... [--names k=n1,n2...] [--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... [-y]` / `runo retry RUN [--submit]` | scancel / failed・cancelled を created に戻す |
+| `runo cancel RUN... [--why TEXT] [-y]` / `runo retry RUN [--submit] [-y]` | scancel（`--why` は note に残る）/ failed・cancelled を created に戻す（理由付きで cancel された run は確認を取る） |
 | `runo status [RUN...]` / `runo sync [RUN...]` / `runo log RUN [--err] [-n N] [-f]` | 状態表示 / Slurm から更新 / log 表示 |
 | `runo list [PATH] [--all] [--since 30d] [--case] [--sweep] [--status] [--tag] [--scratch] [--archived] [--json]` | run 一覧 |
 | `runo note RUN [TEXT]` / `runo pin RUN [--off] [--reason]` | ノート追記・表示 / pin |
 | `runo summarize RUN... [--force]` | adapter の要約を `analysis/summary.json` に書く |
 | `runo mv RUN... [--dest DIR] [--label L] [--why TEXT]` | `runs/` 配下で改名・移動。id、入力、sweep、ノートは保つ。submitted / running と archived は不可 |
-| `runo archive RUN... ` / `runo archive --older-than 90d` / `runo restore RUN` | `runs/_archive/` へ移動 / 戻す |
+| `runo archive RUN\|DIR... [--superseded-by RUN\|DIR --why TEXT]` / `runo archive --older-than 90d` / `runo restore RUN` | `runs/_archive/` へ移動 / 戻す。移動前に全対象を検査し、指定した RUN が終了していなければ何も動かさない。DIR は配下の run（系列）で、created / submitted / running と pinned を除いて表示する。`--superseded-by` は置き換え先（その run から `--from` で派生した run、無ければ指定した全 run）を `superseded_by` に記録し、`--why` をノートに残す |
 | `runo delete RUN... [-y]` | created・failed・cancelled・scratch の run を削除 |
 | `runo tidy [--apply] [--only KIND] [--older-than AGE] [--purge-work RUN...]` | 整理候補の表示と実行 |
 | `runo migrate-v1 [--dry-run] [--apply-delete-test-runs] [-y]` | v1 project の変換 |

{runops-2.2.0 → runops-2.3.0}/pyproject.toml

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

{runops-2.2.0 → runops-2.3.0}/src/runops/__init__.py

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

{runops-2.2.0 → runops-2.3.0}/src/runops/cli.py

@@ -488,7 +488,7 @@ def submit_cmd(
     if all_runs:
         if runs and len(runs) > 1:
             raise UsageError("--all takes at most one DIR")
-        under = Path(runs[0]).resolve() if runs else project.runs_dir
+        under = project.runs_subdir(runs[0]) if runs else project.runs_dir
         targets = [
             m
             for m in project.iter_runs(under)
@@ -524,6 +524,9 @@ def submit_cmd(
 @app.command()
 def cancel(
     runs: list[str] = typer.Argument(...),
+    why: str = typer.Option(
+        "", "--why", help="Reason, recorded as a note (e.g. 'wrong input; replaced by ...')."
+    ),
     yes: bool = typer.Option(False, "-y", "--yes"),
 ) -> None:
     """scancel submitted/running runs."""
@@ -533,7 +536,7 @@ def cancel(
     targets = _resolve(project, runs)
     _confirm("Cancel " + ", ".join(f"{m.id} (job {m.job_id})" for m in targets) + "?", yes)
     for m in targets:
-        cancel_run(project, m, runner=_runner())
+        cancel_run(project, m, runner=_runner(), why=why, by=_actor())
         out.print(f"cancelled {m.id}")
 
 
@@ -541,12 +544,17 @@ def cancel(
 def retry(
     run: str = typer.Argument(...),
     submit: bool = typer.Option(False, "--submit"),
+    yes: bool = typer.Option(False, "-y", "--yes"),
 ) -> None:
     """Reset a failed/cancelled run to created (work/ is kept)."""
-    from runops.ops.submit import retry_run
+    from runops.ops.submit import cancel_reason, retry_run
 
     project = _project()
     m = project.resolve_run(run)
+    reason = cancel_reason(m)
+    if reason:
+        # Someone cancelled it on purpose (e.g. to fix and replace it); do not revive it silently.
+        _confirm(f"{m.id} was cancelled: {reason}. Retry anyway?", yes)
     retry_run(project, m)
     out.print(f"{m.id} -> created")
     if submit:
@@ -687,7 +695,7 @@ def list_cmd(
         if s not in {state.value for state in RunState}:
             raise UsageError(f"unknown status {s!r}")
     flt = ListFilter(
-        path=path.resolve() if path else None,
+        path=project.runs_subdir(path) if path else None,
         show_all=show_all,
         since=parse_age(since) if since else None,
         cases=cases or [],
@@ -771,39 +779,58 @@ def summarize(
 
 @app.command()
 def archive(
-    runs: Optional[list[str]] = typer.Argument(None),
+    runs: Optional[list[str]] = typer.Argument(
+        None, help="Runs, or directories under runs/ (a series)."
+    ),
     older_than: str = typer.Option(
         "", "--older-than", help="Archive completed runs older than this (e.g. 90d)."
     ),
+    superseded_by: str = typer.Option(
+        "",
+        "--superseded-by",
+        help="Run or series directory that replaces these runs; recorded in each manifest.",
+    ),
+    why: str = typer.Option("", "--why", help="Reason, recorded in each run's notes."),
     yes: bool = typer.Option(False, "-y", "--yes"),
 ) -> None:
     """Move terminal runs to runs/_archive/ (same relative path)."""
     from datetime import datetime
 
-    from runops.ops.tidy import archive_run
+    from runops.ops.tidy import ArchivePlan, archive_run, plan_archive
 
     project = _project()
+    if superseded_by and not why:
+        raise UsageError("--superseded-by needs --why")
     if older_than:
-        if runs:
+        if runs or superseded_by:
             raise UsageError("give RUNs or --older-than, not both")
         cutoff = datetime.now().astimezone() - parse_age(older_than)
-        targets = [
-            m
-            for m in project.iter_runs()
-            if m.status == RunState.COMPLETED
-            and not m.pinned
-            and (m.created_datetime() or cutoff) < cutoff
-        ]
+        plan = ArchivePlan(
+            targets=[
+                m
+                for m in project.iter_runs()
+                if m.status == RunState.COMPLETED
+                and not m.pinned
+                and (m.created_datetime() or cutoff) < cutoff
+            ]
+        )
     else:
-        targets = _resolve(project, runs or [])
-    if not targets:
+        plan = plan_archive(project, runs or [], superseded_by=superseded_by)
+    for m, reason in plan.skipped:
+        out.print(f"  skip {m.id}  {reason}  {project.rel(m.run_dir)}")
+    if not plan.targets:
         out.print("nothing to archive")
         return
-    for m in targets:
-        out.print(f"  {m.id}  {project.rel(m.run_dir)}")
-    _confirm(f"Archive {len(targets)} runs?", yes)
-    for m in targets:
-        dst = archive_run(project, m)
+    for m in plan.targets:
+        line = f"  {m.id}  {m.status.value}  {project.rel(m.run_dir)}"
+        if m.id in plan.superseded_by:
+            line += f"  -> {', '.join(plan.superseded_by[m.id])}"
+        out.print(line)
+    _confirm(f"Archive {len(plan.targets)} runs?", yes)
+    for m in plan.targets:
+        dst = archive_run(
+            project, m, superseded_by=plan.superseded_by.get(m.id), why=why, by=_actor()
+        )
         out.print(f"archived {m.id} -> {project.rel(dst)}")
 
 

{runops-2.2.0 → runops-2.3.0}/src/runops/harness.py

@@ -20,12 +20,13 @@ COMMANDS = """\
 | `runo submit RUN... [--partition P]` / `runo submit --all DIR` | sbatch created runs |
 | `runo sync` / `runo status RUN` / `runo log RUN [--err]` | refresh state from Slurm / show / read logs |
 | `runo list [--all] [--case C] [--status S] [--json]` | recent + active runs (old, scratch, archived hidden) |
-| `runo cancel RUN` / `runo retry RUN` | stop a job / reset failed or cancelled to created |
+| `runo cancel RUN [--why T]` / `runo retry RUN` | stop a job / reset failed or cancelled to created |
 | `runo note RUN "text"` / `runo pin RUN --reason TEXT` | append an observation / protect a key run |
 | `runo summarize RUN` | adapter summary into analysis/summary.json |
 | `runo tidy` / `runo tidy --apply` | list / apply cleanup (expired scratch, stale failures, old runs) |
 | `runo mv RUN... [--dest DIR] [--label L] --why TEXT` | rename / move runs, keeping ids and inputs |
-| `runo archive RUN` / `runo restore RUN` / `runo delete RUN` | move to runs/_archive / back / remove |
+| `runo archive RUN\\|DIR... [--superseded-by RUN\\|DIR --why T]` | move finished runs (or a series) to runs/_archive |
+| `runo restore RUN` / `runo delete RUN` | move back / remove |
 | `runo build SIM` | build a local_source simulator into .runops/build |
 | `runo doctor` / `runo update` | check environment / upgrade simulator packages and skills |"""
 
@@ -42,8 +43,9 @@ def render_block(project: Project, skills: list[str]) -> str:
     return f"""{BEGIN}
 # {project.config.name}
 
-This is a runops project: simulation runs are tracked as directories under
-`runs/`, each with a `manifest.toml` owned by runops. Use the `runo` CLI.
+This is a runops project. Each run is a directory under `runs/` with a `manifest.toml`
+that runops owns. The `runo` CLI creates, submits, tracks and tidies runs, and acts on
+the project found from the current directory.
 
 ## Simulators
 
@@ -53,30 +55,36 @@ This is a runops project: simulation runs are tracked as directories under
 
 {COMMANDS}
 
-## Rules
-
-- The request sets what may happen: "make/create" creates runs only; "run/submit" also
-  submits; "try/test" allows a short `--scratch` run and its submission, never a
-  production submit. Earlier runs may fill in parameters, not add actions.
-- Before `submit`, `sweep --apply --submit`, or `submit --all`, show the target runs,
-  partition and resources, and get confirmation.
-- After a production submit is accepted, report the job ids and stop. When asked to
-  watch, check once for early failure, then near the expected end; no `tail -f` loops.
-- Never edit `manifest.toml` or a run's `input/` by hand. Change the case or create a
-  new run with `--set` / `new --from`. To rename or move a run, use `runo mv`, not a
-  re-created copy.
-- Express variations as runs, not cases: use `runo new CASE --set k=v`,
-  `runo new --from RUN --set k=v`, or `runo sweep`. Create a new case only when the
-  structure of the base input files changes.
-- Always pass `--why` when creating runs. Use `--scratch` for smoke/debug runs.
+## How to work here
+
+- **Let the request set the actions.** "make/create" means creating runs; "run/submit"
+  also submits; "try/test" means a short `--scratch` run that you may submit. Earlier
+  runs can supply parameters, while the request decides what happens.
+- **Confirm before compute is spent.** Before any submit, show the runs, partition,
+  resources and core-hours, and wait for the go-ahead. Once Slurm accepts the jobs,
+  report the job ids and end the turn; Slurm does the waiting. When asked to watch,
+  check once early and once near the expected end.
+- **Work within this project.** Requests such as "resubmit everything" mean the runs
+  under `runs/` here: find them with `runo sync` and `runo list`. Account-wide `squeue`
+  and `sacct` help diagnose, but other projects and unmanaged jobs belong to other
+  sessions, so act on them only when the user names them. If nothing here matches, say so.
+- **Change runs through `runo`.** `runo` writes each run's manifest and `input/`, so
+  they stay an exact record of what ran.
+  Express a change as a new run (`runo new --from RUN --set k=v`, `runo sweep`) and
+  rename or regroup with `runo mv`. Variations are runs; a new case is for a different
+  structure of the base input.
+- **Leave the reason behind.** Give each new run `--why`. When you cancel runs to fix or
+  replace them, add `runo cancel --why`, so later sessions and `runo retry` leave them
+  stopped. When a new series replaces an old one, ask whether the old one is still
+  needed and archive it with `--superseded-by`.
 
 ## Notes
 
-- Observations about one run: `runo note RUN "..."` (or the run's `notes.md`).
-- Conclusions across runs and next decisions: append to `LOG.md` under a dated heading.
-- Reusable knowledge (formulas, methods, pitfalls): `notes/<topic>.md`, one file per
-  topic. Extend an existing file instead of creating a similar one.
-- Do not create note files anywhere else (`research/`, `analysis/*.md`, `runs/`).
+Notes live in three places, where `runo context` and the next session find them:
+- one run: `runo note RUN "..."`;
+- conclusions across runs and next decisions: `LOG.md`, appended under a dated heading;
+- reusable knowledge (formulas, methods, pitfalls): `notes/<topic>.md`, extending the
+  existing file for a topic.
 
 ## Skills
 

{runops-2.2.0 → runops-2.3.0}/src/runops/manifest.py

@@ -133,6 +133,14 @@ class Manifest:
     def sweep(self) -> str:
         return str(self.section("origin").get("sweep", ""))
 
+    @property
+    def parent_run(self) -> str:
+        return str(self.section("origin").get("parent_run", ""))
+
+    @property
+    def superseded_by(self) -> list[str]:
+        return [str(r) for r in self.run.get("superseded_by", [])]
+
     @property
     def params(self) -> dict[str, Any]:
         return dict(self.section("params"))
@@ -190,7 +198,8 @@ class Manifest:
             # Enough for an agent to compare runs without another command.
             "params": self.params,
             "changed_keys": list(self.section("variation").get("changed_keys", [])),
-            "parent_run": str(self.section("origin").get("parent_run", "")),
+            "parent_run": self.parent_run,
+            "superseded_by": self.superseded_by,
             "exe_hash": str(self.section("simulator").get("exe_hash", "")),
             "input_hash": str(self.section("identity").get("input_hash", "")),
             # Walltime evidence for the next run: elapsed of the latest attempt.

{runops-2.2.0 → runops-2.3.0}/src/runops/ops/submit.py

@@ -172,7 +172,12 @@ def _current_exe_hash(manifest: Manifest) -> str:
 
 
 def cancel_run(
-    project: Project, manifest: Manifest, *, runner: CommandRunner = default_runner
+    project: Project,
+    manifest: Manifest,
+    *,
+    runner: CommandRunner = default_runner,
+    why: str = "",
+    by: str = "",
 ) -> None:
     with project.run_lock():
         manifest.reload()
@@ -187,10 +192,22 @@ def cancel_run(
         if attempts:
             attempts[-1]["finished_at"] = now
             attempts[-1]["slurm_state"] = "CANCELLED"
+        if why:
+            (attempts[-1] if attempts else manifest.job)["cancel_reason"] = why
+            manifest.add_note(f"cancelled: {why}", by or "runops")
         manifest.set_status(RunState.CANCELLED)
         manifest.save()
 
 
+def cancel_reason(manifest: Manifest) -> str:
+    """The ``cancel --why`` reason of a cancelled run, if its latest cancel gave one."""
+    if manifest.status != RunState.CANCELLED:
+        return ""
+    attempts = manifest.job.get("attempts") or []
+    record = attempts[-1] if attempts else manifest.job
+    return str(record.get("cancel_reason", ""))
+
+
 def retry_run(project: Project, manifest: Manifest) -> None:
     with project.run_lock():
         manifest.reload()

{runops-2.2.0 → runops-2.3.0}/src/runops/ops/tidy.py

@@ -144,9 +144,76 @@ def apply_candidates(
 # ---- archive / restore / delete --------------------------------------
 
 
-def archive_run(project: Project, manifest: Manifest) -> Path:
+_TERMINAL = (RunState.COMPLETED, RunState.FAILED, RunState.CANCELLED)
+
+
+@dataclass
+class ArchivePlan:
+    targets: list[Manifest] = field(default_factory=list)
+    skipped: list[tuple[Manifest, str]] = field(default_factory=list)
+    superseded_by: dict[str, list[str]] = field(default_factory=dict)  # old id -> new ids
+
+
+def plan_archive(project: Project, refs: list[str], *, superseded_by: str = "") -> ArchivePlan:
+    """Check every target before anything moves.
+
+    A RUN that cannot be archived is an error. A directory (a series) stands for the
+    runs below it; its submitted/running/created and pinned runs are skipped and listed.
+    With *superseded_by* (a RUN or a series directory), each old run records the
+    replacement runs derived from it (``origin.parent_run``), or all of them when none is.
+    """
+    if not refs:
+        raise UsageError("give at least one RUN or directory")
+    explicit: dict[str, Manifest] = {}
+    expanded: dict[str, Manifest] = {}
+    for ref in refs:
+        runs, is_dir = project.resolve_runs(ref)
+        for m in runs:
+            (expanded if is_dir else explicit)[m.id] = m
+    plan = ArchivePlan()
+    for run_id, m in {**expanded, **explicit}.items():
+        if inside(m.run_dir, project.runs_dir / ARCHIVE_DIR):
+            reason = "already archived"
+        elif m.status not in _TERMINAL:
+            reason = m.status.value
+        elif m.pinned and run_id not in explicit:
+            reason = "pinned"
+        else:
+            plan.targets.append(m)
+            continue
+        if run_id in explicit:
+            raise UsageError(f"{run_id} is {reason}; only terminal runs can be archived")
+        plan.skipped.append((m, reason))
+    if superseded_by:
+        new, _ = project.resolve_runs(superseded_by)
+        old_ids = {m.id for m in plan.targets} | {m.id for m, _ in plan.skipped}
+        if old_ids & {m.id for m in new}:
+            raise UsageError("--superseded-by must not include the runs being archived")
+        for m in plan.targets:
+            derived = [r.id for r in new if r.parent_run == m.id]
+            plan.superseded_by[m.id] = derived or [r.id for r in new]
+    return plan
+
+
+def archive_run(
+    project: Project,
+    manifest: Manifest,
+    *,
+    superseded_by: list[str] | None = None,
+    why: str = "",
+    by: str = "",
+) -> Path:
+    """Move a terminal run to ``runs/_archive/``; record replacements and *why* if given."""
+    with project.run_lock():
+        manifest.reload()
+        return _archive_locked(project, manifest, superseded_by or [], why, by)
+
+
+def _archive_locked(
+    project: Project, manifest: Manifest, superseded_by: list[str], why: str, by: str
+) -> Path:
     status = manifest.status
-    if status not in (RunState.COMPLETED, RunState.FAILED, RunState.CANCELLED):
+    if status not in _TERMINAL:
         raise UsageError(f"{manifest.id} is {status.value}; only terminal runs can be archived")
     src = manifest.run_dir.resolve()
     archive_root = project.runs_dir / ARCHIVE_DIR
@@ -170,6 +237,12 @@ def archive_run(project: Project, manifest: Manifest) -> Path:
             "archived_at": now_iso(),
         }
     )
+    if superseded_by:
+        moved.run["superseded_by"] = list(superseded_by)
+        text = f"superseded by {', '.join(superseded_by)}"
+        moved.add_note(f"{text}: {why}" if why else text, by or "runops")
+    elif why:
+        moved.add_note(f"archived: {why}", by or "runops")
     moved.set_status(RunState.ARCHIVED)
     moved.save()
     project.update_index(moved.id, dst)