FerryCat

FerryCat：契約駆動型クロスホスト AI エージェント引き継ぎバス

英語 • 中文

FerryCat（ferrycat）は、Model Context Protocol（MCP）と Node.js 組み込みの node:sqlite（WAL モード）を基盤とする、軽量かつ決定論的なクロスホスト AI エージェントの引き継ぎ・コードレビュー用バスです。
Google Antigravity、WorkBuddy、Claude Code、Cursor など、分離されたデスクトップ IDE エージェントホストを、コンテキストのずれや古いファイルに対する盲目的なレビューを招くことなく、別々の OS プロセス間で安全に橋渡しできるように設計されています。

📖 詳しく読む：FerryCat の開発を始めた理由：2 つの AI コーディングホストが同じデスクトップで稼働するとき

---

主な課題とエンジニアリングによる解決策

公式の MCP Tasks 仕様（2025-11 / 2026-07）は、単一の Client ↔ Server 接続内での長時間実行オペレーションには対応していますが、開発者のワークステーションにおけるホスト間の連携は解決していません。

1. stdio プロセスの分離：デスクトップ IDE は、メモリー空間が分離され、それぞれ異なる Node.js ランタイムで動作するローカル MCP サーバーを、独立した子プロセスとして起動します。
2. 古いコードに対する気付かれない盲目的なレビュー（Stale Context）：タスクをホスト A からホスト B に引き継ぐ際、IDE の未フラッシュのバッファー、ブランチの切り替え、レビュー中の編集などにより、引き継ぎ先のエージェントが古いコードを監査し、もっともらしくても無効な結論を出すことがあります。
3. コンテキストウィンドウの肥大化：チャットウィンドウ間で何百行ものソースコードを貼り付けると、両側でトークン消費が重複します。
4. 構造化されていない引き継ぎ結果：自由形式の文章による応答では、決定論的なスキーマを強制できません。そのため、後続処理での利用が不安定になり、無限の再試行ループに陥りやすくなります。

FerryCat は、人がスケジュールを管理する契約駆動型の SQLite WAL バスによって、これらの障害要因を解消します。

[Developer]             [Host A: Antigravity]            [~/.ferrycat/mesh.db]            [Host B: WorkBuddy]
     |                            |                                |                               |
     |-- 1. "Dispatch review" --->|                                |                               |
     |                            |-- dispatch_contract() -------->| Write status = SUBMITTED      |
     |                            |   (Full SHA-256 + Line Bounds) | Store size / sha256 snapshot  |
     |                            |                                |                               |
     |-- 2. Switch IDE: "Poll" ---|--------------------------------|------------------------------>|
     |                            |                                |<-- poll_next_task() ----------|
     |                            |                                |    (Atomic claim changes===1  |
     |                            |                                |     + Verify disk SHA-256)    |
     |                            |                                |                               |-- Read local files
     |                            |                                |<-- fulfill_contract() --------|-- Re-verify SHA-256
     |                            |                                |    (Validate Ajv JSON Schema  |   & submit JSON
     |                            |                                |     -> status = COMPLETED)    |
     |                            |                                |                               |
     |-- 3. Switch IDE: "Inspect" |                                |                               |
     |                            |-- inspect_mesh_state() ------->| Read-only query of COMPLETED  |
     |<-- Present structured res -|                                |                               |

---

アーキテクチャの主要な柱

1. 決定論的な7状態マシン

すべての状態遷移は、楽観的同時実行制御（changes === 1）を伴う明示的な SQL トランザクションにバインドされ、幽霊状態や宙に浮いた状態を排除します。

                  dispatch_contract()
                          │
                          ▼
                    ┌───────────┐
                    │ SUBMITTED │ (Queue TTL: default 1800s)
                    └─────┬─────┘
                          │
                 poll_next_task()
         ┌────────────────┼────────────────┐
         │ (Queue TTL)    │ (Hash Match)   │ (Missing / Size Diff / SHA-256 Mismatch)
         ▼                ▼                ▼
   ┌───────────┐    ┌───────────┐   ┌───────────────┐
   │ TIMED_OUT │    │  CLAIMED  │   │ POINTER_STALE │ (Terminal: Rejects blind review)
   └───────────┘    └─────┬─────┘   └───────────────┘
      ▲                   │ (Exec TTL: default 300s)
      │          fulfill_contract()
      │  ┌────────────────┼────────────────┬────────────────┐
      └──┤ (Exec TTL)     │ (Schema Valid) │ (Retries > 2)  │ (Mid-Review File Edit)
         │                ▼                ▼                ▼
         │          ┌───────────┐   ┌───────────────────┐ ┌───────────────┐
         └──────────│ COMPLETED │   │ VALIDATION_FAILED │ │ POINTER_STALE │
                    └───────────┘   └───────────────────┘ └───────────────┘

CLAIMED 状態のコントラクトに対するホルダー側のライフサイクル制御（すべて agent_id === target_agent が必要です）：

呼び出し	遷移	ガード条件
release_contract	CLAIMED → SUBMITTED（キューの末尾、新しいキュー期間）	extend_count をリセットします（更新回数の上限はホルダーごとです）が、retry_count は保持します。スキーマ検証失敗時のサーキットブレーカーはコントラクト単位の割り当てなので、解放してリトライ回数の上限を回避することはできません。絶対有効期限を過ぎると拒否されます。コントラクトごとに最大3回まで解放できます。
extend_ttl	CLAIMED → CLAIMED（claimed_at = now）	有効期間内に呼び出す必要があります。ホルダーごとに最大5回まで更新でき、now ≥ created_at + 4 × queue_ttl_sec になると拒否されます。
fail_contract	CLAIMED → FAILED（終端状態）	reason が必要で、WORKER_FAILED: <reason> として保存されます。有効期間が終了した後に報告が届いた場合は、理由を付けて TIMED_OUT になります。

2. ファイル全体の SHA-256 フィンガープリント、事前検証と TOCTOU ソフト失敗のバッファリング（ADR-0004）

• ディスパッチ時のスナップショット：dispatch_contract はディスク上の対象ファイルを読み取り、バイト数の size、ファイル全体の sha256（64桁の16進数）、first_line、last_line を記録します。ファイルが過去3秒以内に変更されていた場合、未保存の IDE バッファが存在する可能性を依頼者に知らせる warning が出力されます。
• クレーム時の検証：poll_next_task は 存在確認 -> バイト数 -> ファイル全体の SHA-256 の順に検証します（何も変更しない IDE の保存を許容するため、mtime_ms のみを理由に拒否することはありません）。不一致の場合は、IDE による一時的な書き込みを除外するため 150ms 待機して一度再試行し、その後コントラクトを POINTER_STALE としてマークします。
• 事前検証（verify_contract）：ワーカーやスクリプトが送信前にポインターの健全性（valid: true、または変更されたファイルの一覧を伴う valid: false）を監査できる、厳密な読み取り専用チェックです。
• TOCTOU ソフト失敗のバッファリング：fulfill_contract はディスク上のポインターのフィンガープリントをチェックします。変更されたポインターが検出された場合：
  • 1回目のストライクでは RETRY_NEEDED を返し、コントラクトを CLAIMED のまま維持して実行期間を更新し、復旧手順（git stash / git checkout -- <file>）とともに変更されたファイルを一覧表示します。
  • 2回目のストライクでは終端状態の POINTER_STALE に遷移し、送信されたレビューのペイロード全体を salvaged_result_json に保存するため、レビュー作業が失われることはありません。
• TOCTOU 競合の縮小：ディスク上のバイト列を読み取ってからデータベースの行をコミットするまでに発生するマイクロ秒単位の競合は、ファイルベースのシステムでは排除できません。しかし、FerryCat の二重検証（poll 時と fulfill 時）により、TOCTOU の時間枠を数分間の無検証レビューから、ミリ秒未満のアトミックな SQL 遷移境界まで大幅に縮小します。

3. 上限付きスキーマ検証（RETRY_NEEDED $\le 2$）

• 出力はキャッシュされた Ajv バリデーターを使用してコントラクトの JSON Schema に照らして検証され、エラーは簡潔な1行のパスにまとめられます（例：["/passed: must be boolean"]）。
• 検証に失敗しても、最大2回まではコントラクトを CLAIMED のまま維持し、すぐに自己修正できるよう RETRY_NEEDED を返します（拒否のたびに実行期間も更新されます）。3回目の失敗では、コントラクトは終端状態の VALIDATION_FAILED に遷移します。

4. 2段階 TTL と読み取り後書き込み方式のスイープ

• queue_ttl_sec（SUBMITTED の場合はデフォルトで1800秒）と exec_ttl_sec（claimed_at から計測）を分離し、キュー期間の終盤でクレームされたタスクが実行中に早期タイムアウトするのを防ぎます。
• exec_ttl_sec のデフォルトは task_type に応じて段階化されています。code_review / architecture_audit は1800秒（深い推論や人間が介在する処理）、implementation / test_generation は300秒です。exec_ttl_sec が明示的に指定された場合は、常にその値が優先されます。
• poll_next_task は期限切れの行に対して UPDATE を試みる前に、ロックフリーの SELECT COUNT(*) プローブを実行します。inspect_mesh_state は厳密な読み取り専用です。

5. 多層防御によるパスセキュリティ

• dispatch と worker の両方の検証パスで、workspace_root 内にパスが収まるよう強制し、機密ファイルのパターン（.env*、*.pem、*.key、id_rsa*、*credentials*、*secret*、.npmrc、.git/config）をブロックします。
• パス解決：workspace_root には絶対パスを指定することを強く推奨します。相対パスが指定された場合は、path.resolve を使用して process.cwd() を基準に決定的に解決されます。

6. 脅威モデルとセキュリティ上の前提（ローカルワークステーション IPC）

• 信頼環境の前提：FerryCat は、同じ OS ユーザーアカウントで動作する分離された IDE ホストをつなぐ、信頼されたローカルワークステーションバスとして意図的に設計されています。呼び出し元とワーカーは、ローカルファイルシステム（workspace_root）と SQLite データベース（~/.ferrycat/mesh.db）を共有します。
• 防御範囲：パスの包含チェック（assertSafePointerPath）と機密ファイルパターンのフィルターにより、引き継ぎ時の意図しないワークスペース外へのアクセス、シンボリックリンクのたどり、認証情報や秘密情報を含むファイルの偶発的な漏えいを防ぎます。
• 対象範囲外（非目標）：FerryCat は、悪意のあるローカルプロセスや AGENT_NAME を偽装する敵対的なエージェントに対する、敵対的なサンドボックス化、マルチテナント分離、ネットワーク認可を提供しません。

---

適用範囲の境界（FerryCat を使用すべきでない場合）

1. 分離されたファイルシステム：FerryCat はファイル参照によってコンテキストを引き渡すため、両方のホストが同じローカル workspace_root にアクセスできる必要があります。
2. 単純な単一ターンのクエリ：ホスト間の引き継ぎごとに、人間が明示的にウィンドウを3回切り替える必要があります（約15～25秒のオーバーヘッド）。
3. 無人のバックグラウンドパイプライン：デスクトップ IDE ホストはリクエスト／レスポンスモデルに従うため、アイドル状態の MCP サーバーから非同期に起動することはできません。無人のマルチステップパイプラインには、PatchCat のようなスタンドアロンの DAG ワークフローエンジンを使用してください。

---

クイックスタート

1. 推奨：ゼロインストールでの MCP マウント（npx を使用）

ローカルへのクローンや手動コンパイルは不要です。npx -y ferrycat を使用して、IDE の MCP 設定に直接マウントします。

Antigravity の設定

%USERPROFILE%\.gemini\antigravity\mcp_config.json（macOS/Linux では ~/.gemini/antigravity/mcp_config.json）を編集します。

{
  "mcpServers": {
    "ferrycat": {
      "command": "npx",
      "args": ["-y", "ferrycat"],
      "env": {
        "AGENT_NAME": "antigravity"
      }
    }
  }
}

WorkBuddy / Claude Code / Cursor / Codex の設定

対象ホストの MCP 設定で、対応する AGENT_NAME を設定します。

{
  "mcpServers": {
    "ferrycat": {
      "command": "npx",
      "args": ["-y", "ferrycat"],
      "env": {
        "AGENT_NAME": "workbuddy"
      }
    }
  }
}

2. グローバルインストールとソースからのビルド

• グローバル CLI インストール：

  npm install -g ferrycat
  

  次に、MCP 設定で "command": "ferrycat" を設定するだけです。
• ローカルソースからのビルド（コントリビューター向け）：

  git clone https://github.com/GuoBug/FerryCat.git
  cd FerryCat
  npm install
  npm run build
  npm test
  

  ローカルパスを使用してマウントします。 "command": "node"、"args": ["--experimental-sqlite", "/path/to/FerryCat/dist/index.js"]。

---

CLI をすぐに使える環境（ferrycat-cli）

IDE 内で動作する MCP サーバーとして機能するだけでなく、FerryCat は本格的な CLI ユーティリティ（ferrycat-cli または npx ferrycat-cli）も提供します。同じ ~/.ferrycat/mesh.db SQLite WAL データベースと Zod 検証コントラクトを共有するこの CLI を使うと、開発者はターミナルを離れることなく、メッシュの状態を調べ、ワーキングツリーの安全性を検証し、自動化された CI／Git スクリプトと連携できます。

1. ターミナルでの視覚的な確認（ASCII ステータステーブル）

ホスト間のすべての引き継ぎとエラー理由を、ASCII テーブル形式で確認します。

# View all contracts in an ASCII table
npx ferrycat-cli inspect

# Filter by target agent (e.g., only tasks for antigravity)
npx ferrycat-cli inspect --target antigravity

2. 事前検証（変更前の監査）

レビュー作業をコミットする前に、ディスク上のポインターファイルの整合性をコントラクトのベースライン SHA-256 と照合して監査し（ADR-0004）、誤検出による受け渡しを排除します。

npx ferrycat-cli verify <CONTRACT_ID>

3. ローカル CI とヘッドレスワーカーの実行

キューをポーリングしてタスクを取得し、失敗時に自動でクローズしながら、ローカルのレビュー／テストスクリプトを実行します。

# Safely run a script upon task arrival (no shell quotation hazards)
npx ferrycat-cli worker --agent codex --mode=exec --exec-file ./scripts/review.sh

---

公開されている MCP ツール

ツール名	役割	トランザクションの動作
dispatch_contract	リクエスター	パスのブラックリストを適用 $\to$ ファイル全体の SHA-256 と行の範囲を計算 $\to$ SUBMITTED を挿入します。
poll_next_task	ワーカー	期限切れの TTL を走査（読み取り後に書き込み） $\to$ changes === 1 で確保（CLAIMED） $\to$ ディスク上の SHA-256 を検証（または POINTER_STALE に設定）します。
fulfill_contract	ワーカー	SHA-256 を再検証（TOCTOU ガード） $\to$ Ajv JSON Schema を検証（RETRY_NEEDED による再試行は最大 2 回、3 回目は VALIDATION_FAILED に設定） $\to$ COMPLETED に設定します。
release_contract	ワーカー（保持者）	CLAIMED のコントラクトをキューの末尾に SUBMITTED として戻します。retry_count は保持されます（コントラクト単位のサーキットブレーカー）。extend_count はリセットされます。リリースは最大 3 回で、絶対有効期限を過ぎると拒否されます。
extend_ttl	ワーカー（保持者）	ハートビート：実行ウィンドウを再開（claimed_at = now）します。更新は最大 5 回で、合計有効期間には上限があります。
fail_contract	ワーカー（保持者）	必須の reason を指定して、CLAIMED のコントラクトを終端状態の FAILED に設定します。
verify_contract	ワーカー／任意（読み取り専用）	事前チェック：コントラクトの状態を変更せずに、ディスク上のポインターファイルをベースラインの SHA-256 と照合して検証します（ADR-0004）。
inspect_mesh_state	任意（読み取り専用）	コントラクトの状態、出力、および動的な is_logically_expired フラグを純粋に読み取り専用で照会します。

💡 アーキテクチャ決定記録とエンジニアリング検証：

• ADR-0001：クロスホスト SQLite WAL バスと人手によるスケジュール設定のポーリングモデル（60 秒のブロッキング待機や単一接続の MCP Tasks ではなく、node:sqlite WAL と poll_next_task を採用する理由）
• ADR-0002：ファイル全体の SHA-256 フィンガープリント、TOCTOU ガード、クロスモデル監査（コンテキストの陳腐化を防ぐ仕組みと、実環境でのクロスホスト検証記録）
• ADR-0003：GUI サンドボックスと CLI プロセスのハイブリッドレイヤリングアーキテクチャ、および起動境界（デスクトップの HITL 承認と社内 CLI のデュアルチャネル自律性）
• ADR-0004：レビューと変更の分離（SRM）、TOCTOU のソフトフェイルバッファリング、イミュータブルなベースラインプロトコル（同時編集や善意のレビュアーによる編集でレビューが中断されるのを防ぐ方法）
• FerryCat の要件バックログとロードマップ

---

著者について
Guo Qiang（GuoBug）、プラットフォームエンジニアリングとグロースを専門とするプロダクトエンジニアです。現在は AI ワークフローのオーケストレーション、DAG 状態機械、決定論的システムアーキテクチャに注力しています。
オープンソースとホームページ：https://github.com/GuoBug · https://guobug.github.io
ワークフローエンジンのアーキテクチャ、トポロジカルスケジューリング、開発者体験に関するお問い合わせや議論を歓迎します。