背景セッションが実行中のまま固まっていた — agents ビューにハートビートを添えて停滞を数分で捕まえる

ハートビートをフックで刻む

次の問いは「誰が刻印を書くか」です。

素直に考えると、セッションと並走する監視プロセスを別に立てたくなります。けれど私はこれを避けました。監視プロセスを立てると、今度はその監視プロセスが死んでいないかを誰が見るのか、という入れ子の問題が始まるからです。背景セッションが12本あれば、監視プロセスも12本。管理対象が倍になります。

そこで使うのが PostToolUse フックです。Claude Code はツール呼び出しのたびにフックを発火できます。ここにハートビートの書き込みを仕込めば、セッションが何か作業をするたびに、副作用として刻印が更新されます。別プロセスは要りません。セッションが死ねばフックも一緒に止まるので、監視の入れ子も生まれません。

まず、刻印を書く小さなスクリプトです。

#!/usr/bin/env bash
# heartbeat.sh — 呼ばれるたびに現在のセッションの生存刻印を更新する
# 使い方: heartbeat.sh <phase>
set -euo pipefail
 
# セッション名は起動時に環境変数で渡しておく(可読名と揃える)
SESSION="${CC_SESSION_NAME:-unknown}"
PHASE="${1:-tool}"
 
# クラウド同期フォルダを避け、ローカルの tmpfs に置く(理由は後述)
HB_DIR="/tmp/cc-heartbeat"
mkdir -p "$HB_DIR"
 
# エポック秒で書く。date 文字列は使わない(タイムゾーン事故の回避)
NOW=$(date +%s)
 
# 1行の JSON を原子的に置き換える(途中まで書いた壊れた行を読ませない)
TMP="$(mktemp "${HB_DIR}/.tmp.XXXXXX")"
printf '{"session":"%s","ts":%s,"phase":"%s"}\n' "$SESSION" "$NOW" "$PHASE" > "$TMP"
mv -f "$TMP" "${HB_DIR}/${SESSION}.json"

mktemp に書いてから mv で置き換えているのは、リコンサイラが「書きかけの半分の行」を読む可能性を消すためです。同じディレクトリ内の mv は原子的なので、読み手は常に完全な1行だけを見ます。

このスクリプトをフックから呼びます。プロジェクトの .claude/settings.json に次を加えます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "heartbeat.sh tool:${TOOL_NAME}"
          }
        ]
      }
    ]
  }
}

matcher を * にして全ツールで発火させ、フェーズにツール名を載せています。こうすると刻印を見るだけで「最後に何をしていたか」まで分かります。朝、停滞していたセッションのフェーズが tool:web_fetch で止まっていれば、ネットワーク待ちのハングだと即座に見当がつきます。

停滞を判定するリコンサイラ

刻印が溜まったら、それを見張る側です。リコンサイラは「ハートビートのディレクトリを舐めて、古い刻印を停滞候補として吐く」だけの小さなプログラムで足ります。

#!/usr/bin/env node
// reconcile.mjs — ハートビートの鮮度を見て停滞候補を報告する
import { readdirSync, readFileSync } from "node:fs";
 
const HB_DIR = "/tmp/cc-heartbeat";
const NOW = Math.floor(Date.now() / 1000);
 
// しきい値: 単発ツールの最長より十分に長く取る(理由は落とし穴の節で)
const STALE_SEC = 300;   // 5分無音で「停滞の疑い」
const DEAD_SEC = 900;    // 15分無音で「ほぼ停止」
 
const rows = [];
for (const f of readdirSync(HB_DIR)) {
  if (!f.endsWith(".json")) continue;
  let hb;
  try {
    hb = JSON.parse(readFileSync(`${HB_DIR}/${f}`, "utf8"));
  } catch {
    continue; // 壊れた行はスキップ(原子置換で基本起きないが保険)
  }
  const age = NOW - hb.ts;
  let state = "alive";
  if (age >= DEAD_SEC) state = "dead?";
  else if (age >= STALE_SEC) state = "stale?";
  rows.push({ session: hb.session, ageSec: age, phase: hb.phase, state });
}
 
// 古い順に並べ、疑わしいものだけ非ゼロ終了で知らせる
rows.sort((a, b) => b.ageSec - a.ageSec);
const suspect = rows.filter((r) => r.state !== "alive");
for (const r of rows) {
  console.log(`${r.state.padEnd(6)} ${String(r.ageSec).padStart(5)}s  ${r.session}  (${r.phase})`);
}
process.exit(suspect.length > 0 ? 1 : 0);

これを 3〜5分おきに cron や launchd で回します。非ゼロ終了を通知に紐づければ、停滞が起きた瞬間に手元へ届きます。私は macOS の launchd から呼び、疑わしいセッションが1本でもあれば通知センターに出すようにしています。実行の完了そのものを翌朝に検証する後付けの手当てとしては、以前終了時アサーションで無音の成功を疑う記事に書きましたが、ハートビートはその手前で、走っている最中の生死を見るための層です。両方を持っておくと、走行中の停滞と終了後の空振りの両方に網がかかります。

出力はこんな具合になります。

dead?    7412s  wallpaper-ios-deps-0706-a3f  (tool:web_fetch)
alive      41s  gemilab-changelog-0706-9c2  (tool:bash)
alive      12s  blog-crash-summary-0706-77e  (tool:edit)

先頭の1行が、まさに冒頭で7時間放置してしまったセッションです。phase が tool:web_fetch で止まっているので、外部取得の応答待ちでハングしたのだと一目で分かります。

実際にどれだけ縮んだか

導入前と導入後で、停滞に気づくまでの時間がどう変わったかを記録しました。私の環境（夜間に平均10〜12セッション、うち停滞は週に1〜2本程度）での二週間の実測です。

数字そのものより、私にとって大きかったのは「朝いちばんに agents ビューを不安な気持ちで開かなくなった」ことでした。停滞が起きれば数分で通知が来ると分かっているので、夜間の実行を以前より落ち着いて任せられるようになりました。可観測性への投資は、たいてい計測値より先に心理的な余裕として返ってきます。

つまずいたところ

きれいに動くまでに、三つのつまずきがありました。どれも、実際に走らせてみるまで見えなかったものです。

思考中の無音を取りこぼす

PostToolUse フックは、その名のとおりツール呼び出しの後にしか発火しません。つまり、セッションがツールを一切呼ばずに長考しているあいだは、ハートビートが更新されません。これを停滞と誤判定してしまうと、正常な深い推論を殺しかねません。

私はここで、しきい値を「最長の正当な単発ツール」より十分に長く取ることで折り合いをつけました。加えて、フェーズに tool: の接頭辞を残しておくと、「最後の活動がツールだった」ことが分かるので、長考中の無音と本当のハングをある程度見分けられます。厳密にやるなら、セッション開始直後に一度 phase:thinking の刻印を置き、以降ツールごとに上書きする二段構えにすると、起動直後の空白も塞げます。

クラウド同期フォルダでの書き込み競合

最初、ハートビートをワークスペース直下に置いていて、これが失敗でした。私の作業フォルダはクラウド同期されていて、数秒おきの小さな書き込みが同期処理と競合し、リコンサイラがときどき古い内容を読んでしまったのです。

解決は単純で、ハートビートは同期されないローカルの /tmp に置くこと。刻印は消えても構わない一時情報ですから、永続化する必要がありません。クラウド同期フォルダのファイル実体化まわりの落とし穴は根が深く、クラウド同期ワークスペースのファイル実体化を自動化する記事で別途整理しています。生きているうちの高頻度な書き込みは、同期対象から外すのが鉄則です。

長い単発ツールの誤検知

code_execution のような、ひとつのツール呼び出しが90秒近くかかるものがあります。しきい値をこれより短く取ると、正当な長いツール実行の最中に「停滞」と鳴ってしまいます。

だから STALE_SEC は、環境で起こりうる最長の単発ツール実行より確実に長く設定します。私は最長でも2分程度なので、5分をしきい値にしています。ここは各自のワークロード次第で、まずは広めに取って誤検知を潰し、慣れてから詰めるのが安全です。可観測性のしきい値設計全般は、SRE サイトリライアビリティエンジニアリング（Betsy Beyer ほか編）のアラート設計の章が、誤報とアラート疲れのトレードオフを丁寧に扱っていて、私はしきい値を決めるときに何度も読み返しました。

なぜこの形にしたか

最後に、設計判断の理由をひとつだけ残しておきます。

このハートビート層は、agents ビューを置き換えるものではありません。補完するものです。agents ビューはプレゼンスを、コミット相関はトレーサビリティを、終了時アサーションは完了の検証を、そしてハートビートはライブネスを担います。それぞれが別の問いに答えていて、どれか一つで全部を賄おうとすると、必ずどこかに穴が開きます。長時間セッションのメモリ肥大を見張るRSS ウォッチドッグの設計も、この可観測性の網の一目です。

無人運用の信頼性は、派手な一手ではなく、こうした小さな網目を重ねることで少しずつ上がっていくのだと、私自身、運用を続けるなかで感じています。

まず試すなら、heartbeat.sh を1つ書いて PostToolUse フックに繋ぎ、今夜の背景セッションを1本だけ見張ってみてください。翌朝、刻印の鮮度が更新され続けているのを確認できれば、そこがライブネス層の出発点になります。

夜の実行を安心して任せられる状態が、少しでも増えれば嬉しいです。お読みいただきありがとうございました。