heartbeat

ハートビートオーケストレーター

Heartbeat スキルは、Agentic OS のバックグラウンドプロセッサーとして機能します。.agent/state/tasks.json キューを読み込み、保留中のタスクを特定して適切なスキルに割り当て、完了時にタスクのステータスを更新します。

仕組み

このスキルの scripts/ ディレクトリにある heartbeat.py スクリプトを使用して、キューを管理します。

1. スコープ付きキューを確認する: 取り組むタスクがわからない場合は、最初に heartbeat.py scopes を実行します。_<batch>_extension.<queue> パスにある、取り出し可能なキューをすべて一覧表示し、準備完了・進行中・完了の件数を示します。
2. タスクを取り出す: 次のタスクを取得するには、heartbeat.py pop（レガシーモード）または heartbeat.py pop --scope _round3_extension.ag_implementation_queue（スコープ付きモード）を実行します。tasks.json に _*_extension キューが存在する場合、--scope なしの pop は終了コード 11 で拒否されます。該当する --scope を指定してください。
3. 実行する: タスクの詳細を読み、適切なスキル（例：osint、deep-research）を使用してタスクを実行します。
4. 復旧と再試行: タスクが予期せず失敗した場合、自律型エージェントは正式に失敗として扱う前に、タスクの処理を最大 2 回再試行する必要があります。
5. 完了／失敗を記録する: heartbeat.py complete <task_id> --scope <path> --outcome '{"result": "..."}'（スコープ付き）または heartbeat.py complete <task_id> --outcome '...'（レガシー）を実行します。失敗は .agent/state/errors.json に記録されます。

パスはエージェントによって異なります。

• Gemini / Antigravity：python3 ~/.gemini/skills/heartbeat/scripts/heartbeat.py …
• Claude：python3 ~/.claude/skills/heartbeat/scripts/heartbeat.py …

（どちらのパスもシンボリックリンクを経由して ~/github/claude-skills にある同じ正規スクリプトを参照するため、動作は同じです。）

スコープ付きキュー（1.2.0 で追加）

tasks.json に _round3_extension のようなバッチメタデータブロックがある場合、その配下にある各リストのすべての項目に task_id フィールドが含まれていれば、それを スコープ付きキュー として扱います。このスクリプトは、プロジェクトの AGENTS.md § Agentic OS 運用規律に基づき、次の 3 つのルールを適用します。

• 明示的なキューを優先する: スコープ付きキューが存在する場合、--scope なしの pop は拒否されます（終了コード 11）。スコープ付きキューが有効な間は、より広範な pending リストを使用できません。
• ブロックされた項目をスキップする: gh_issue または task_id が兄弟の blocked_on_* 配列のいずれかに含まれるキュー項目は、自動的にスキップされます。スクリプトは、スキップした項目とその理由を表示します。
• キューが空になったら停止する: スコープ付きキューに ready 項目がなくなると、終了コード 10 で終了し、エビデンスレポートを記入して、pending を探し回らずに停止するよう通知します。

例：

heartbeat.py scopes
# _round3_extension.ag_implementation_queue  (3 ready / 0 in_progress / 0 completed / 3 total)

heartbeat.py pop --scope _round3_extension.ag_implementation_queue
# pops the first ready item, marks status=in_progress in place

heartbeat.py complete round3-edit-item-33-southern-qualifier \
  --scope _round3_extension.ag_implementation_queue \
  --outcome '{"pr": 502, "merged": true}'

古い in_progress 項目の処理（1.2.0 で追加）

tasks.json に、クラッシュまたは引き継ぎが発生した前回のセッションからの in_progress 項目がある場合、pop は終了コード 12 で拒否され、古い項目が表示されます。次のいずれかの方法で解決してください。

heartbeat.py clear-stale          # move them all back to pending
heartbeat.py pop --accept-stale --scope <path>   # adopt and proceed

これにより、新しいエージェントが別のセッションの未完了の作業を気付かないまま引き継ぐことを防ぎます。これは、既知の失敗パターンです。

終了コード

コード	意味
0	通常の pop ／保留中のタスクなし（レガシーとの後方互換性）
10	スコープ付きキューが空です。エビデンスレポートを記入して停止してください
11	スコープが存在しますが、--scope が指定されていません。いずれかを選択してください
12	古い in_progress 項目があります。解消するか、--accept-stale を指定してください
13	呼び出し側がブロックされた項目を直接取り出そうとしました（予約済み）
14	--scope のパスがリスト形式の辞書に解決されませんでした

ラッパー（heartbeat-runner シェル、AG 起動スクリプト）は、これらのコードに応じて処理を分岐する必要があります。終了コード 10 は停止、11／12 はオペレーターによる判断が必要、14 は設定の不具合を意味します。

タスク形式

tasks.json のレガシー形式（引き続きサポートされています）：

{
  "pending": [
    {
      "id": "task-123",
      "priority": "high",
      "description": "Deep research the current state of local LLM orchestration.",
      "assigned_skill": "deep-research",
      "project_id": "claude-skills",
      "agent_id": "antigravity",
      "user_id": "matthias",
      "created_at": "2026-04-25T12:00:00Z",
      "completed_at": null
    }
  ],
  "in_progress": [],
  "completed": [],
  "failed": []
}

スコープ付きキュー形式（レガシーフィールドと併用）：

{
  "pending": [...],
  "in_progress": [],
  "completed": [],
  "failed": [],
  "_round3_extension": {
    "ag_implementation_queue": [
      {
        "order": 1,
        "task_id": "round3-edit-item-33-southern-qualifier",
        "gh_issue": 496,
        "estimate": "frontmatter only on 2 providers; ~10 min",
        "risk": "minimal"
      }
    ],
    "blocked_on_client": [
      { "items": "Spanish PDFs", "issues": [390, 391], "blocker": "translator pending" }
    ]
  }
}

このスクリプトは、_*_extension 配下にあり、すべての項目に task_id が含まれるものを、取り出し可能なキューとして扱います。blocked_on_ で始まるキーはフィルター入力であり、キューではありません。ag_pushed_branches のようなメタデータリスト（項目に task_id が含まれないもの）は、scopes による検出時に無視されます。

実行

呼び出されたとき（またはエージェントの起動時に自動実行されるとき）、安定性とコンテキスト長を維持するため、明示的にキューを処理しきるよう求められない限り、Heartbeat は一度に 1 件のタスクを処理します。スコープ付きキューがあるプロジェクトでは、エージェントは --scope を渡し、処理済みキューの停止シグナルに従わなければなりません。許可なくキュー外の作業を選ぶことは、このバージョンが防止するために作成された、文書化済みの失敗パターンです。

エージェント型 OS との統合

コア OS コンポーネントとして、このスキルは自身の実行内容を .agent/state/last-run.json に必ず記録し、処理したタスクとその結果を記載しなければなりません。1.2.0 の last-run スキーマでは scope フィールドが追加され、ラッパーがスコープ付きの呼び出しとレガシーの呼び出しを区別できるようになりました。