monster-orchestrator 3.2.4 → 3.2.6

package/scripts/monster-deathcheck

@@ -0,0 +1,805 @@
+#!/usr/bin/env python3
+"""monster-deathcheck — 死んだ monster を即座に見つける（読み取り専用）
+
+なぜ必要か:
+  monster-orchestrator の reconcile() は
+    - 死を events.log に書かない（state.json のフィールドを黙って書き換えるだけ）
+    - 正常完了も異常死も latest_event = session_end で区別できない
+    - 誰かが list_monsters を叩いた時にしか回らない（pull 型）
+  ため、「死んだこと」も「いつ死んだか」もレジストリからは分からない。
+
+  さらに reconcile() は寿命判定を生存判定の内側に置いているため、寿命切れの
+  monster が「先に session が消えていた」だけで timeout ではなく
+  "session disappeared" とラベルされる。実測では同一事象（寿命ちょうどの死）が
+  片方 timeout・片方 session disappeared になっていた（53cb1d2a / e8df2b33）。
+
+このスクリプトは既存の記録だけから死を判定する。何も書き換えず、何も kill しない。
+tmux は has-session のみ（attach / send-keys / kill 系は一切使わない）。
+
+判定の核（events.log から計算できる、レジストリに無い区別）:
+  最後の user_prompt 以降に idle / awaiting_input / subagent_stop が
+  一度も出ないまま session_end が来ていたら、そのターンは完走していない
+  = ターン途中で消えた（異常死）。
+  逆に awaiting_input を経てから session_end なら、指示通り止まった（正常完了）。
+
+寿命切れの予告（Q9）:
+  reconcile() は send_to_monster / list_monsters / spawn_monster から呼ばれる
+  （src/tools/send.ts:9 ほか）。つまり **寿命切れの monster に話しかけると、
+  その send 自体が reconcile を回して tmuxKillSession() を起こす**。
+  ⇒ 予告が無いと「反応が無いから声をかける → その行為が殺す」経路に入る。
+     寿命切れ相手への送信は、無駄なのではなく有害。
+
+  ただし実測では、寿命で終了した 28 体のうち 23 体は awaiting_input で駐機中
+  （＝仕掛かりが無く無害）だった。全件に鳴らすとノイズが本物を埋めるため、
+  「寿命が近く、かつまだ働いている」ものだけを警告対象にする。
+
+usage:
+  monster-deathcheck                  人が読む形式で全 monster を判定（レジストリ外の GHOST を含む）
+  monster-deathcheck --json           機械可読（艦隊コレクタのリモートプローブ用）
+  monster-deathcheck --verify         測定器自体を検証（対照実験）
+  monster-deathcheck --notify-preview 鳴らすなら何を送るかを表示するだけ
+                                      🚨 送信はしない。LINE への実発火は POLICY 案件で CTO 裁定待ち
+
+exit code:
+  0 = 人が今すぐ見るべきものは無い
+  1 = 人が今すぐ見るべきものを検出した（死亡 DIED-* / レジストリ外 GHOST）
+      ⚠️ GHOST は死亡ではない。「生きているのに見えない」側であり、放置すると
+         成果が失われるという一点で死亡と同じ扱いにしている
+  2 = 測定不能（state.json や tmux が読めない等）。⚠️ 0 と混同しないこと:
+      「異常なし」と「測れなかった」を同じ値にすると、今日の不検出を再現する
+  ※ 寿命警告（EXPIRING-*）は exit code を変えない。まだ何も失われていないため、
+    「1 が返った＝人が見るべきものがある」と混ぜない
+
+環境変数:
+  MONSTER_ROOT      monster レジストリの場所（既定 ~/.claude/monsters）
+  TMUX_BIN          tmux の絶対パス（既定は PATH → /opt/homebrew/bin/tmux の順に探索）
+                    ⚠️ 非対話 SSH では PATH に /opt/homebrew/bin が乗らないため必要
+  CLAUDE_PROJECTS_ROOT  transcript の場所（既定 ~/.claude/projects）
+  MONSTER_WARN_MIN  寿命の予告閾値・分（既定 30。ダッシュボード表示）
+  MONSTER_CRIT_MIN  寿命の最終警告閾値・分（既定 5。鳴らす想定・現在は未発火）
+"""
+
+import glob
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+
+# 板 #442 ③: 解決の式を全経路で揃える（server=src/paths.ts は MONSTER_MCP_ROOT を honour）。
+#   MONSTER_ROOT は後方互換の別名として残す（従来この道具だけがこの名前を見ていた）。
+ROOT = (os.environ.get("MONSTER_MCP_ROOT")
+        or os.environ.get("MONSTER_ROOT")
+        or os.path.expanduser("~/.claude/monsters"))
+STATE_PATH = os.path.join(ROOT, "state.json")
+EVENTS_PATH = os.path.join(ROOT, "events.log")
+
+# ターンが前に進んだことを示すイベント（これが出ていれば少なくとも1手は完了している）
+PROGRESS = {"idle", "awaiting_input", "subagent_stop"}
+
+# watcher が生きているとみなす session.log の更新間隔（watcher は60秒周期）
+WATCHER_FRESH_SEC = 180
+
+# 人が今すぐ見るべき分類。死亡（DIED-*）と、レジストリ外で生きている GHOST。
+# そして STALLED-*（レジストリ内で生きていない＝応答できない）。
+# GHOST の実害は「成果が見えなくなる」、STALLED の実害は「指揮そのものが誤る」
+#（盤面の稼働数が嘘になり、動けない monster を配車先として数えてしまう）。
+# 寿命警告（EXPIRING-*）はここに入れない——まだ何も失われていないため。
+# 死亡と警告を同じ値にすると「1 が返った＝人が見るべきものがある」という読み方が壊れる。
+URGENT = {"DIED-UNDETECTED", "DIED-MIDTURN", "GHOST",
+          "STALLED-RATE-LIMIT", "STALLED-BACKEND"}
+
+# 鳴らす対象（実発火は CTO 裁定後）
+NOTIFY = {"DIED-UNDETECTED", "DIED-MIDTURN", "GHOST",
+          "STALLED-RATE-LIMIT", "STALLED-BACKEND", "EXPIRING-WORKING"}
+
+VERDICT_ORDER = [
+    "GHOST", "DIED-UNDETECTED", "DIED-MIDTURN",
+    "STALLED-RATE-LIMIT", "STALLED-BACKEND", "STALLED-API-ERROR",
+    "EXPIRING-WORKING", "EXPIRING-PARKED", "ALIVE-UNVERIFIED",
+    "TIMEOUT-KILL", "TIMEOUT-MISLABELED", "COMPLETED-MISLABELED",
+    "ALIVE", "COMPLETED", "UNKNOWN",
+]
+
+# 寿命の閾値（分）
+WARN_MIN = int(os.environ.get("MONSTER_WARN_MIN") or 30)
+CRIT_MIN = int(os.environ.get("MONSTER_CRIT_MIN") or 5)
+
+# 駐機中とみなすイベント。これで止まっているなら仕掛かりが無く、寿命切れは無害。
+PARKED_EVENTS = {"awaiting_input"}
+
+
+class Unmeasurable(Exception):
+    """測定できなかった。異常なしとは違う。"""
+
+
+def resolve_tmux():
+    explicit = os.environ.get("TMUX_BIN")
+    if explicit:
+        return explicit
+    # 非対話 SSH では PATH に homebrew が乗らないので実パスも見る
+    return shutil.which("tmux") or "/opt/homebrew/bin/tmux"
+
+
+def load_state():
+    try:
+        with open(STATE_PATH) as f:
+            state = json.load(f)
+    except FileNotFoundError as e:
+        raise Unmeasurable(f"state.json が無い: {STATE_PATH}") from e
+    except (OSError, json.JSONDecodeError) as e:
+        raise Unmeasurable(f"state.json が読めない: {e}") from e
+    return state.get("monsters", state)
+
+
+def load_events():
+    """monster_id -> [イベント名] を時系列で返す。events.log が無くても致命ではない。"""
+    by_id = {}
+    try:
+        f = open(EVENTS_PATH, errors="replace")
+    except OSError:
+        return by_id
+    with f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                e = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            mid = e.get("monster_id")
+            if mid:
+                by_id.setdefault(mid, []).append(e.get("event", ""))
+    return by_id
+
+
+def tmux_alive(tmux, session, retries=3, delay=0.25):
+    """has-session を複数回撃つ。1回の false を信じないのが reconcile との違い。
+
+    reconcile() は単発 false を即 "stopped" 確定する。8/3 の 902f2dec は
+    それで生きたまま死亡扱いされた（実際にはその後12分働いて完走した）。
+    """
+    if not session:
+        return False
+    for i in range(retries):
+        try:
+            r = subprocess.run([tmux, "has-session", "-t", session],
+                               capture_output=True, timeout=10)
+        except (OSError, subprocess.SubprocessError):
+            return False
+        if r.returncode == 0:
+            return True
+        if i < retries - 1:
+            time.sleep(delay)
+    return False
+
+
+def minutes_until(expires_at, now=None):
+    """残り寿命（分）。パースできなければ None。
+
+    ⚠️ None を「余裕あり」に丸めない。読めなかったものを安全側に倒すと、
+    測れなかったことが異常なしとして描かれる（本件の失敗そのもの）。
+    """
+    if not expires_at:
+        return None
+    try:
+        exp = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+    except (ValueError, AttributeError):
+        return None
+    if exp.tzinfo is None:
+        exp = exp.replace(tzinfo=timezone.utc)
+    now = now or datetime.now(timezone.utc)
+    return (exp - now).total_seconds() / 60.0
+
+
+def classify_expiry(remaining_min, last_event):
+    """寿命が近い running monster を分類する純粋関数（--verify で単体検証する）
+
+    返り値: (verdict, level)。閾値の外なら (None, None)。
+      EXPIRING-PARKED  … awaiting_input で駐機中。仕掛かりが無いので寿命切れは無害。
+                         表示はするが鳴らさない（実測 28 件中 23 件がこれ。
+                         鳴らせばノイズが本物を埋め、今日と同じ失敗になる）
+      EXPIRING-WORKING … まだ働いている。寿命が来れば仕掛かりごと消える。鳴らす対象。
+    """
+    if remaining_min is None or remaining_min > WARN_MIN:
+        return (None, None)
+    if last_event in PARKED_EVENTS:
+        return ("EXPIRING-PARKED", None)
+    return ("EXPIRING-WORKING", "crit" if remaining_min <= CRIT_MIN else "warn")
+
+
+
+# ---------------------------------------------------------------------------
+# ゴースト monster（レジストリ外で生きている monster）
+#
+# tmux にセッションが在るのに state.json にエントリが無い monster が実在する
+# （2026-08-04 実測: 23b47504。spawn 記録は events.log にあるが state.json に無い）。
+# 原因は spawn 時の書き込み競合と推定される。spawn の 3〜6 秒後に、生まれた monster 自身の
+# orchestrator プロセスが bootstrap し、新エントリを含まない state を読んで後から保存するため。
+# ⇒ spawn は、自分の登録を消しうるプロセスを自分で起動している。
+#
+# レジストリ外なので、
+#   - list_monsters に出ない
+#   - stop_monster で止められない（resolveMonsterId が見つけられない）
+#   - reconcile が走査しないので expires_at が効かない
+# ⇒ 止める手段が tmux 直接操作しかない monster になる。
+#
+# 🔑 実害は暴走ではなく「成果が誰からも見えなくなること」。
+#    実測の 23b47504 は 1 時間 19 分の測定を完走して結果をファイルに残していた。
+#    レジストリだけを見ている限り、この 1 体は原理的に検出できない。
+# ---------------------------------------------------------------------------
+
+SESSION_PREFIX = "monster-"
+
+
+def list_tmux_monster_sessions(tmux):
+    """tmux 上の monster セッション名を列挙する。
+
+    ⚠️ 「列挙できなかった」を「0 件」に丸めない。
+       丸めると、tmux が死んでいるときにゴーストが 0 件に見える
+       ＝測定器が「無い」と誤る側に倒れる（本件で最も避けたい失敗）。
+    ただし「サーバが起動していない」は正真正銘の 0 件なので、そこは区別する。
+    """
+    try:
+        r = subprocess.run([tmux, "list-sessions", "-F", "#{session_name}"],
+                           capture_output=True, text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError) as e:
+        raise Unmeasurable(f"tmux を実行できない: {e}") from e
+    if r.returncode != 0:
+        err = (r.stderr or "").strip()
+        if "no server running" in err or "no current session" in err:
+            return set()
+        raise Unmeasurable(f"tmux list-sessions が失敗した: {err[:120]}")
+    return {ln.strip() for ln in r.stdout.splitlines()
+            if ln.strip().startswith(SESSION_PREFIX)}
+
+
+def load_session_events():
+    """tmux セッション名ごとに (終了を観測したか, spawn 時刻) を返す。
+
+    state.json はプルーニングされるため、古い停止済み monster の tmux セッションが
+    残っていると差集合に出てしまう。events.log 側で終了を観測済みのものは除外する。
+    """
+    ended, spawned = set(), {}
+    try:
+        f = open(EVENTS_PATH, errors="replace")
+    except OSError:
+        return ended, spawned
+    with f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                e = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            sess = e.get("session")
+            if not sess:
+                continue
+            ev = e.get("event", "")
+            if ev in ("session_end", "stopped"):
+                ended.add(sess)
+            elif ev == "spawned":
+                spawned[sess] = e.get("ts", "")
+    return ended, spawned
+
+
+def ghost_sessions(live_sessions, known_sessions, ended_sessions):
+    """レジストリ外セッションを判定する純関数（--verify で単体検証する）。
+
+    live   : tmux に実在するセッション名
+    known  : state.json が知っているセッション名
+    ended  : events.log で終了を観測済みのセッション名（＝残骸。ゴーストではない）
+    """
+    return sorted(s for s in live_sessions
+                  if s not in known_sessions and s not in ended_sessions)
+
+
+def find_ghosts(monsters, tmux):
+    known = {m.get("tmux_session") for m in monsters.values() if m.get("tmux_session")}
+    live = list_tmux_monster_sessions(tmux)
+    ended, spawned = load_session_events()
+    out = []
+    for sess in ghost_sessions(live, known, ended):
+        short = sess[len(SESSION_PREFIX):]
+        # 🚨 GHOST と STALLED は同時に成立しうる（実測: 23b47504）。
+        #    片方が他方を隠さないよう、ghost 側にも API 状態を載せる。
+        gid = next((k for k in monsters if k.startswith(short)), None) or short
+        readable, is_err, status = read_last_api_state(gid)
+        out.append({
+            "session": sess,
+            "short_id": short,
+            "stalled": classify_api_error(is_err, status) if readable else None,
+            "stalled_unverified": not readable,
+            "spawned_at": spawned.get(sess, ""),
+            "detail": ("tmux にセッションが在るが state.json にエントリが無い。"
+                       "list_monsters に出ず、stop_monster で止められず、"
+                       "reconcile が走査しないので寿命も効かない"),
+        })
+    return out
+
+
+# ---------------------------------------------------------------------------
+# STALLED — レジストリ内で生きていない monster
+#
+# 週次上限などで API が応答を返さなくなった monster は、
+#   - state.json では running
+#   - tmux has-session も通る
+#   - last_action_at も新しい
+#   - session.log も watcher が 60 秒ごとに更新し続ける
+# ⇒ **既存のどの判定でも「生きて働いている」と読める。** 実際には次の 1 文字も出力できない。
+#
+# GHOST が「レジストリ外で生きている」なら、これは「レジストリ内で生きていない」。対になる死角。
+# 実害は成果の消失ではなく **指揮の誤り**——盤面の稼働数が嘘になり、
+# 動けない monster を配車先として数えてしまう（2026-08-04 に実際に発生）。
+#
+# 🚨 判定にペインの文言を使わない。文言は変わる。
+#    Claude Code 自身の transcript（~/.claude/projects/<home>/*.jsonl）の
+#    最後の type=assistant エントリに、機械可読なフィールドが載る:
+#      isApiErrorMessage: true / apiErrorStatus: 429 / error: "rate_limit"
+#      message.model: "<synthetic>"（API が応答せず CLI が合成した応答）
+#    実測（18 体）で偽陽性・偽陰性ともゼロ。
+# ---------------------------------------------------------------------------
+
+PROJECTS_ROOT = os.environ.get("CLAUDE_PROJECTS_ROOT") or os.path.expanduser("~/.claude/projects")
+
+# 最後の assistant を探すときに遡る行数。transcript 全体を読むのは高価なので末尾のみ見る。
+TRANSCRIPT_TAIL_LINES = 60
+
+
+def transcript_path(monster_id):
+    """monster の transcript を探す。見つからなければ None。
+
+    ディレクトリ名は cwd をスラグ化したもので、機体やユーザ名で変わる。
+    monster_id での前方一致 glob にして、ユーザ名に依存しないようにする。
+    """
+    hits = glob.glob(os.path.join(PROJECTS_ROOT, f"*monsters-{monster_id}*", "*.jsonl"))
+    if not hits:
+        return None
+    return max(hits, key=os.path.getmtime)
+
+
+def read_last_api_state(monster_id):
+    """最後の assistant エントリの API 状態を返す。
+
+    返り値 (readable, is_api_error, status)
+      readable=False は「読めなかった」。⚠️ これを「正常」に丸めない。
+    """
+    path = transcript_path(monster_id)
+    if path is None:
+        return (False, None, None)
+    try:
+        with open(path, errors="replace") as f:
+            lines = f.readlines()[-TRANSCRIPT_TAIL_LINES:]
+    except OSError:
+        return (False, None, None)
+    for line in reversed(lines):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            e = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if e.get("type") != "assistant":
+            continue
+        # 🚨 最後の assistant だけを見る。過去に 429 を食って回復したものを
+        #    「停止中」と誤検出しないため（一時的な 429 はリトライで回復する）。
+        return (True, bool(e.get("isApiErrorMessage")), e.get("apiErrorStatus"))
+    return (False, None, None)
+
+
+def classify_api_error(is_api_error, status):
+    """API エラー状態から判定名を返す純関数（--verify で単体検証する）。
+
+    429 と 5xx を分ける。同じ「応答できない」でも回復見込みが違うため——
+    429 は上限リセットまで戻らない。5xx は次の瞬間に戻るかもしれない。
+    """
+    if not is_api_error:
+        return None
+    if status == 429:
+        return "STALLED-RATE-LIMIT"
+    if isinstance(status, int) and 500 <= status < 600:
+        return "STALLED-BACKEND"
+    return "STALLED-API-ERROR"
+
+
+def stalled_detail(verdict, status):
+    if verdict == "STALLED-RATE-LIMIT":
+        return ("API が上限で応答しない（HTTP 429）。state.json は running・tmux も在席・"
+                "session.log も更新され続けるが、次の 1 文字も出力できない。"
+                "盤面の稼働数が嘘になるので、配車先として数えないこと")
+    if verdict == "STALLED-BACKEND":
+        return (f"API がバックエンド障害で応答しない（HTTP {status}）。"
+                "429 と違い、次の瞬間に回復しうる")
+    return f"API が応答しない（HTTP {status}）"
+
+def tail_since_last_prompt(events):
+    """最後の user_prompt / spawned 以降のイベント列を切り出す"""
+    last = None
+    for i, ev in enumerate(events):
+        if ev in ("user_prompt", "spawned"):
+            last = i
+    return events[last:] if last is not None else events
+
+
+def classify(mid, rec, events_by_id, tmux):
+    """1体を判定して (verdict, detail) を返す"""
+    events = events_by_id.get(mid, [])
+    tail = tail_since_last_prompt(events)
+    ended = "session_end" in tail
+    progressed = bool(set(tail) & PROGRESS)
+    status = rec.get("status")
+
+    # --- running とされているもの: 実在を確認する（偽陽性を避けるためリトライ付き）
+    if status == "running":
+        if ended:
+            return ("DIED-UNDETECTED",
+                    "state.json は running だが events.log には session_end がある"
+                    "（誰も list_monsters を叩いていないので気づかれていない）")
+        if not tmux_alive(tmux, rec.get("tmux_session", "")):
+            return ("DIED-UNDETECTED",
+                    "state.json は running だが tmux セッションが3回とも取れない")
+
+        # tmux に居ても API が応答しないことがある。寿命警告より先に見る——
+        # 応答できない monster に「あと N 分」と言っても意味がないため。
+        readable, is_err, status = read_last_api_state(mid)
+        if not readable:
+            # ⚠️ 読めなかったものを ALIVE に丸めない（正常と未確認は別物）
+            return ("ALIVE-UNVERIFIED",
+                    "tmux セッション在席を実測（3回確認）／"
+                    "⚠️ transcript が読めず、API に応答できるかは未確認")
+        stalled = classify_api_error(is_err, status)
+        if stalled:
+            return (stalled, stalled_detail(stalled, status))
+
+        # 生きている。寿命が近いなら予告する（Q9）
+        remaining = minutes_until(rec.get("expires_at"))
+        verdict, _level = classify_expiry(remaining, events[-1] if events else "")
+        if verdict == "EXPIRING-PARKED":
+            return (verdict,
+                    f"残り {remaining:.0f} 分。awaiting_input で駐機中なので"
+                    "寿命切れは無害（鳴らさない）")
+        if verdict == "EXPIRING-WORKING":
+            return (verdict,
+                    f"🚨 残り {remaining:.0f} 分で作業中。寿命が来れば仕掛かりごと消える。"
+                    "この状態で send_to_monster を撃つと reconcile が走って"
+                    "その送信自体が kill を起こす")
+        if remaining is None:
+            return ("ALIVE", "tmux セッション在席を実測（3回確認）"
+                             "／⚠️ expires_at が読めず残り寿命は不明")
+        return ("ALIVE", f"tmux セッション在席を実測（3回確認）／残り {remaining:.0f} 分")
+
+    if status == "timeout":
+        return ("TIMEOUT-KILL",
+                "orchestrator の寿命切れ kill。作業途中でも予告なく殺される")
+
+    # 停止理由は stop_reason ではなく last_action の "stopped: " 接頭辞に入る（実測）。
+    # stop_reason フィールドは全件 null だった。
+    last_action = rec.get("last_action") or ""
+    if last_action.startswith("stopped:"):
+        return ("COMPLETED", f"明示停止: {last_action[8:70].strip()}")
+    if rec.get("stop_reason"):
+        return ("COMPLETED", "stop_monster による明示停止（理由あり）")
+
+    if last_action == "session disappeared":
+        # ここが本題。session disappeared は死因ではなくラベルにすぎない。
+        expires = rec.get("expires_at") or ""
+        found_at = rec.get("last_action_at") or ""
+        if expires and found_at and found_at > expires:
+            return ("TIMEOUT-MISLABELED",
+                    f"寿命({expires})を過ぎてから発見({found_at})。"
+                    "本来 timeout だが session が先に消えたため disappeared と誤ラベル")
+        if ended and not progressed:
+            return ("DIED-MIDTURN",
+                    "最後の user_prompt 以降 idle/awaiting_input が一度も出ないまま "
+                    "session_end。ターン途中で消えた")
+        if ended and progressed:
+            return ("COMPLETED-MISLABELED",
+                    "awaiting_input を経て session_end。正常完了だが state.json は "
+                    "disappeared と記録（reconcile が後から拾っただけ）")
+        return ("UNKNOWN", "events.log に session_end が無い。判定不能")
+
+    return ("COMPLETED", f"status={status}")
+
+
+def count_watchers(monsters):
+    """孤児 watcher を数える（#36: stopped 後も session.log を書き続ける）"""
+    now = time.time()
+    live, orphan = [], []
+    for mid, rec in monsters.items():
+        p = os.path.join(ROOT, mid, "session.log")
+        try:
+            fresh = now - os.path.getmtime(p) <= WATCHER_FRESH_SEC
+        except OSError:
+            continue
+        if not fresh:
+            continue
+        short = rec.get("short_id", mid[:8])
+        (live if rec.get("status") == "running" else orphan).append(short)
+    return sorted(live), sorted(orphan)
+
+
+def collect():
+    """判定結果をまとめて返す。--json と人間向け表示の共通の元。"""
+    monsters = load_state()
+    events_by_id = load_events()
+    tmux = resolve_tmux()
+
+    results = []
+    for mid, rec in monsters.items():
+        verdict, detail = classify(mid, rec, events_by_id, tmux)
+        remaining = minutes_until(rec.get("expires_at"))
+        results.append({
+            "short_id": rec.get("short_id", mid[:8]),
+            "verdict": verdict,
+            "detail": detail,
+            "workdir": rec.get("workdir", ""),
+            "spawned_at": rec.get("spawned_at", ""),
+            "expires_at": rec.get("expires_at", ""),
+            # ダッシュボードが「あと何分か」を出せるように、running には必ず載せる
+            "remaining_min": None if remaining is None else round(remaining),
+        })
+    ghosts = find_ghosts(monsters, tmux)
+    live, orphan = count_watchers(monsters)
+    return {
+        "host": os.uname().nodename,
+        "user": os.environ.get("USER", ""),
+        "monster_root": ROOT,
+        "thresholds": {"warn_min": WARN_MIN, "crit_min": CRIT_MIN},
+        "monsters": results,
+        "watchers": {"live": live, "orphan": orphan},
+        "ghosts": ghosts,
+        "urgent": sum(1 for r in results if r["verdict"] in URGENT) + len(ghosts),
+        "expiring": sum(1 for r in results if r["verdict"] == "EXPIRING-WORKING"),
+    }
+
+
+def notify_preview(report):
+    """鳴らすなら何を送るかを表示するだけ。
+
+    🚨 送信はしない。LINE mikoto ops への実発火は POLICY 案件で CTO 裁定待ちのため、
+    このスクリプトには送信コードを一切持たせていない（フラグの消し忘れで
+    誤発火する余地を残さないため、経路そのものを作らない）。
+    """
+    targets = [r for r in report["monsters"] if r["verdict"] in NOTIFY]
+    ghosts = report.get("ghosts") or []
+    print("=== 鳴らす経路のプレビュー（送信はしない）===")
+    print(f"  宛先（予定）: LINE mikoto ops  ／  現在の状態: 未発火（CTO 裁定待ち）")
+    for g in ghosts:
+        print(f"  [レジストリ外] {g['short_id']} {g['session']}")
+        print(f"          {g['detail']}")
+    if not targets and not ghosts:
+        print("  送る対象なし")
+        return
+    for r in sorted(targets, key=lambda x: (x["verdict"], x["short_id"])):
+        dead = r["verdict"] in URGENT
+        # 死んだ monster に「残り寿命」を出さない（無意味なうえ、読む人が
+        # 「まだ生きている」と誤読する）。残り寿命は寿命警告のときだけ意味を持つ。
+        rem = "" if (dead or r["remaining_min"] is None) else f"（残り {r['remaining_min']} 分）"
+        print(f"  [{'死亡' if dead else '寿命間近'}] {r['short_id']} {rem} {r['workdir']}")
+        print(f"          {r['detail']}")
+
+
+def verify_ghost():
+    """ゴースト判定の単体検証（純粋関数なので実データに依存しない）。
+
+    🚨 「ゴースト 1 体」と「ゴースト 0 体」の両方を当てられることを示す。
+       片方しか試さないと、常に 0 を返す壊れた測定器でも緑になる。
+    """
+    KNOWN = {"monster-aaaa1111", "monster-bbbb2222"}
+    cases = [
+        # (live, known, ended, 期待)
+        ("ゴースト 1 体",
+         {"monster-aaaa1111", "monster-cccc3333"}, KNOWN, set(), ["monster-cccc3333"]),
+        ("ゴースト 0 体（全部レジストリにある）",
+         {"monster-aaaa1111", "monster-bbbb2222"}, KNOWN, set(), []),
+        ("ゴースト 0 体（tmux が空）",
+         set(), KNOWN, set(), []),
+        ("終了済みの残骸は除外する",
+         {"monster-dddd4444"}, KNOWN, {"monster-dddd4444"}, []),
+        ("残骸とゴーストが混在",
+         {"monster-dddd4444", "monster-eeee5555"}, KNOWN, {"monster-dddd4444"},
+         ["monster-eeee5555"]),
+        ("複数ゴーストは並べて返す",
+         {"monster-ffff6666", "monster-cccc3333"}, KNOWN, set(),
+         ["monster-cccc3333", "monster-ffff6666"]),
+    ]
+    ok = True
+    for label, live, known, ended, want in cases:
+        got = ghost_sessions(live, known, ended)
+        good = got == want
+        ok = ok and good
+        print(f"  {'OK ' if good else 'NG '}{label:<34} → {got}")
+    return ok
+
+
+def verify_stalled():
+    """API エラー判定の単体検証（純粋関数なので実データに依存しない）。
+
+    🚨 偽陽性の方が危険。働いている monster を STALLED と誤ると「止めてよい」に見える。
+       ⇒ 「エラーでない」ケースを、検出ケースと同じ数だけ並べる。
+    """
+    cases = [
+        # (is_api_error, status, 期待)
+        (True, 429, "STALLED-RATE-LIMIT"),
+        (True, 500, "STALLED-BACKEND"),
+        (True, 503, "STALLED-BACKEND"),
+        (True, 529, "STALLED-BACKEND"),
+        (True, 400, "STALLED-API-ERROR"),
+        (True, None, "STALLED-API-ERROR"),
+        # --- 以下は「検出してはいけない」側 ---
+        (False, None, None),
+        (False, 429, None),      # 過去に 429 を食ったが最後は正常＝回復済み
+        (False, 500, None),
+        (None, None, None),
+        (0, 429, None),
+        ("", 429, None),
+    ]
+    ok = True
+    for is_err, status, want in cases:
+        got = classify_api_error(is_err, status)
+        good = got == want
+        ok = ok and good
+        print(f"  {'OK ' if good else 'NG '}api_error={str(is_err):<5} status={str(status):<5} → {got}")
+    return ok
+
+
+def verify_expiry():
+    """寿命判定の単体検証（純粋関数なので実データに依存しない＝どの機体でも回る）"""
+    W, C = WARN_MIN, CRIT_MIN
+    cases = [
+        # (残り分, 直近イベント, 期待 verdict, 期待 level)
+        (W + 1, "idle", None, None),                       # 閾値の外は何も出さない
+        (W, "idle", "EXPIRING-WORKING", "warn"),           # 境界は含む
+        (C + 1, "user_prompt", "EXPIRING-WORKING", "warn"),
+        (C, "user_prompt", "EXPIRING-WORKING", "crit"),    # 境界は含む
+        (1, "", "EXPIRING-WORKING", "crit"),               # イベント無しは働いている扱い（安全側）
+        (0, "idle", "EXPIRING-WORKING", "crit"),
+        (-5, "idle", "EXPIRING-WORKING", "crit"),          # 既に超過していても出す
+        # 駐機中は閾値内でも鳴らさない（23/28 がこれ）
+        (W, "awaiting_input", "EXPIRING-PARKED", None),
+        (0, "awaiting_input", "EXPIRING-PARKED", None),
+        # 読めなかったものを「余裕あり」に丸めない
+        (None, "idle", None, None),
+    ]
+    ok = True
+    for remaining, last_event, want_v, want_l in cases:
+        got_v, got_l = classify_expiry(remaining, last_event)
+        good = (got_v == want_v and got_l == want_l)
+        ok = ok and good
+        rem = "None" if remaining is None else f"{remaining:>4}"
+        print(f"  {'OK ' if good else 'NG '}残り{rem}分 / {last_event or '(無)':<14} "
+              f"→ {got_v}/{got_l}")
+    return ok
+
+
+def verify():
+    """対照実験: 測定器が既知ケースを正しく分類できるか。
+
+    「0件」「相関なし」を報告する前に測定器の生存を示す、という品質ゲートのため。
+    ⚠️ 期待値は ami機の実データに紐づく。他機では該当なしでスキップされる。
+    """
+    print("--- ゴースト判定（純粋関数・実データ非依存）---")
+    ghost_ok = verify_ghost()
+    print("\n--- API 応答不能の判定（純粋関数・実データ非依存）---")
+    stalled_ok = verify_stalled()
+    print("\n--- 寿命判定（純粋関数・実データ非依存）---")
+    expiry_ok = verify_expiry()
+    print(f"\n--- 死亡判定（既知ケース・実データ依存）---")
+    cases = {
+        # short_id: 期待する分類（人手で一次資料まで確認済み・2026-08-04）
+        "6e3077c4": "DIED-MIDTURN",        # jest 実行中に SIGKILL、transcript も途中で終端
+        "799fafd9": "DIED-MIDTURN",        # 同上
+        "53cb1d2a": "TIMEOUT-KILL",        # reconcile の tmuxKillSession（23ms 後に 137）
+        "e8df2b33": "TIMEOUT-MISLABELED",  # 寿命ちょうど（+15秒で発見）
+        "926c8f08": "TIMEOUT-MISLABELED",  # 寿命 37 分超過後に発見
+        "0893e508": "TIMEOUT-MISLABELED",
+        "7b0bb651": "COMPLETED-MISLABELED",  # 正常完了なのに disappeared と記録
+    }
+    monsters = load_state()
+    events_by_id = load_events()
+    tmux = resolve_tmux()
+    by_short = {r.get("short_id"): (mid, r) for mid, r in monsters.items()}
+
+    ok, checked = True, 0
+    for short, want in cases.items():
+        entry = by_short.get(short)
+        if entry is None:
+            print(f"  -  {short}: この機体には無い（スキップ）")
+            continue
+        checked += 1
+        got, _ = classify(entry[0], entry[1], events_by_id, tmux)
+        if got != want:
+            ok = False
+        print(f"  {'OK ' if got == want else 'NG '}{short}: expect={want} got={got}")
+
+    if checked == 0:
+        print("  （この機体には既知ケースが無い。死亡判定の生存は未確認）")
+        if not (expiry_ok and ghost_ok and stalled_ok):
+            return 1
+        print("\n⚠️ 寿命判定は緑だが、死亡判定は検証できていない")
+        return 2
+    print("\n測定器は" + ("生きている（既知ケースを全て再現）" if ok and expiry_ok and ghost_ok and stalled_ok
+                        else "既知ケースを外した。信用しないこと"))
+    return 0 if (ok and expiry_ok and ghost_ok and stalled_ok) else 1
+
+
+def ghost_as_row(g):
+    """ghost を、判定行と同じ形に畳む（表示順を VERDICT_ORDER に載せるため）。"""
+    detail = g["detail"]
+    if g.get("stalled"):
+        detail += f"／＋ {g['stalled']}: API が応答しない（2 つの死角に同時該当）"
+    elif g.get("stalled_unverified"):
+        detail += "／＋ transcript が読めず、応答可能かは未確認"
+    return {
+        "short_id": g["short_id"],
+        "spawned_at": g.get("spawned_at") or "(spawn 記録なし)",
+        "workdir": g["session"],
+        "detail": detail,
+    }
+
+
+def render(report):
+    buckets = {}
+    for r in report["monsters"]:
+        buckets.setdefault(r["verdict"], []).append(r)
+
+    # 🚨 ghosts は monsters とは別配列で運ばれる（state.json に居ないので monster 行を持てない）。
+    #    ここで bucket に載せないと VERDICT_ORDER の "GHOST" がどの要素にも一致せず、
+    #    ループの外＝最下位に印字される。COMPLETED が 130 件あると 350 行下になり、
+    #    人が読む形式では実質見えない（2026-08-05 に実際に見落としが発生した）。
+    #    表示順は VERDICT_ORDER だけが決める、という一箇所に集約しておく。
+    for g in report.get("ghosts") or []:
+        buckets.setdefault("GHOST", []).append(ghost_as_row(g))
+
+    for verdict in VERDICT_ORDER:
+        items = buckets.get(verdict)
+        if not items:
+            continue
+        print(f"\n■ {verdict} ({len(items)})")
+        for r in sorted(items, key=lambda x: x["spawned_at"]):
+            print(f"  {r['short_id']}  {r['spawned_at']}  {r['workdir']}")
+            print(f"           {r['detail']}")
+
+    w = report["watchers"]
+    print(f"\n■ watcher: 稼働 {len(w['live'])} / 孤児 {len(w['orphan'])}"
+          "（対象がもう居ないのに60秒ごとに空ペインを書き続けている）")
+    if w["orphan"]:
+        print("  " + " ".join(w["orphan"]))
+
+    print(f"\n>>> 今すぐ人が見るべき monster: {report['urgent']} 体")
+    if report["expiring"]:
+        print(f">>> 🚨 寿命が近く、まだ働いている monster: {report['expiring']} 体"
+              "（この相手に送信すると、その送信が kill を起こす）")
+
+
+def main(argv):
+    try:
+        if "--verify" in argv:
+            return verify()
+        report = collect()
+    except Unmeasurable as e:
+        # ⚠️ 測れなかったことを「異常なし」に丸めない。
+        print(f"MEASUREMENT-FAILED: {e}", file=sys.stderr)
+        if "--json" in argv:
+            print(json.dumps({"error": str(e), "measurable": False}, ensure_ascii=False))
+        return 2
+
+    if "--json" in argv:
+        print(json.dumps(report, ensure_ascii=False))
+    elif "--notify-preview" in argv:
+        notify_preview(report)
+    else:
+        render(report)
+    # ⚠️ 寿命警告では exit code を変えない。死亡と警告を同じ値にすると
+    #    「1 が返った＝誰か死んだ」という読み方が壊れる。
+    return 1 if report["urgent"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))