GasTown概念のMNMLエージェント適用設計書

GasTownとは

Steve Yegge氏が開発した、複数AIエージェントをtmux + Dolt DB + git worktreeで並行管理するオーケストレーションシステム。GitHub Issueを入力にし、複数のワーカー（Polecat）がそれぞれ独立したworktreeで同時に作業し、Refinery（マージキュー）で安全に統合する。

本設計書の目的

GasTownの仕組みからMNMLエージェントに有効な部分だけを取り入れる設計を行う。特に以下を重視:

• 並行処理能力の向上: 現行の単一セマフォ(8)から、アカウント別の容量管理へ
• VDU（事業部）立ち上げ: 開発以外のVDU（経理・法務・営業）にも適用できる汎用設計
• 段階的導入: 一度に全てを変えるのではなく、効果の高い順にフェーズ分けして導入

効果（並行処理能力の向上幅）と導入コスト（変更範囲の大きさ）のバランスで優先順位を決定。

GasTownのアプローチ

GasTownはCLAUDE_CONFIG_DIR=~/.claude-accounts/<handle>でCLI起動時に認証を切り替える。gt account switch <handle>コマンドで~/.claudeをシンボリックリンクに差し替える仕組み。

# 設定ファイル: .env に追加
CLAUDE_ACCOUNTS=account1,account2,account3

# アカウント別の認証情報ディレクトリ
~/.claude-accounts/
  ├── account1/    # Max Plan契約 #1
  │   ├── .credentials.json
  │   └── settings.json
  ├── account2/    # Max Plan契約 #2
  │   └── ...
  └── account3/    # Max Plan契約 #3
      └── ...

# AccountPool: アカウント管理（claude_runner.py内）
class AccountSlot:
    name: str                  # "account1"
    config_dir: Path           # ~/.claude-accounts/account1
    semaphore: asyncio.Semaphore  # アカウント別上限
    rate_limit_until: float    # レート制限解除時刻
    active_count: int          # 現在の使用中プロセス数

class AccountPool:
    slots: list[AccountSlot]

    async def acquire() -> AccountSlot:
        """空きのあるアカウントをラウンドロビンで取得。
        全アカウントが満杯なら最初に空くまで待機。"""

    async def release(slot: AccountSlot) -> None:
        """アカウントを返却。"""

    def mark_rate_limited(slot: AccountSlot, until: float) -> None:
        """特定アカウントにレート制限を設定。"""

1. タスクがdispatchされると、AccountPool.acquire()で空きアカウントを取得
2. 取得したアカウントのconfig_dirを環境変数に設定してCLI起動
3. レート制限エラー → そのアカウントだけクールダウン、他アカウントでリトライ
4. タスク完了時にrelease()でアカウントを返却

GasTownのアプローチ

PlanDispatch純粋関数でmin(availableCapacity, batchSize, len(ready))件を選択。SpawnDelayでDB競合を防止。各RigにMaxPolecats上限を設定。

# settings.py に追加
class SchedulerConfig:
    max_concurrent_total: int = 16     # 全体の同時実行上限
    max_concurrent_per_vdu: dict[str, int] = {
        "dev": 8,      # 開発VDU: 最大8並行
        "bo": 4,       # 経理VDU: 最大4並行
        "legal": 2,    # 法務VDU: 最大2並行
        "sales": 2,    # 営業VDU: 最大2並行
    }
    batch_size: int = 3           # 1回のdispatchで最大3タスク
    spawn_delay_sec: float = 2.0  # dispatch間の待機（秒）

※ 上限は設定で変更可能。VDUの実運用を見ながら調整する前提。

全アカウントが満杯の場合、GasTownと同様にタスクをキューに入れて待機させる。

• 現行: セマフォで待機（asyncio.Semaphore.acquire()でブロック）
• 変更後: pending_queueに入れ、枠が空いた時点でFIFO（先入れ先出し）でdispatch
• 優先度: VDU別ではなく、タスクの到着順。ただしCEOからの直接指示は最優先

GasTownのアプローチ

bare repo（.repo.git）を作成し、そこからmayor/refinery/witness/各polecat用のworktreeを分離。各ワーカーが独立したブランチで作業し、ファイル競合を完全排除。

1. 作成: M層がcoderにタスクを委譲する際、worktree_manager.create(task_id)で専用worktreeを作成
2. ブランチ: wt/{task_id}ブランチを自動作成（例: wt/task-abc123）
3. 作業: coderはworktree内のディレクトリをcwdとして作業
4. 完了: M層がレビューOK後、mainへのマージを判断
5. 削除: マージ完了後にworktreeとブランチを自動削除

# 現行
~/Dev/mnml/agents/          # 単一の作業ディレクトリ

# 変更後
~/Dev/mnml/agents/          # mainブランチ（Bot/M層/非coder W層）
~/Dev/mnml/agents/.worktrees/
  ├── wt-task-abc123/       # coder #1 の作業用
  ├── wt-task-def456/       # coder #2 の作業用
  └── wt-task-ghi789/       # coder #3 の作業用

※ GasTownのようにbare repoに変換する方式もあるが、MNMLでは既存のBotプロセスがmainブランチで常駐しているため、通常リポジトリ＋git worktree add方式が安全。

class WorktreeManager:
    base_dir: Path  # ~/Dev/mnml/agents/.worktrees/

    def create(task_id: str, base_branch: str = "main") -> Path:
        """worktreeを作成し、パスを返す。"""

    def remove(task_id: str) -> None:
        """worktreeとブランチを削除。"""

    def list_active() -> list[dict]:
        """アクティブなworktree一覧を返す。"""

    def cleanup_stale(max_age_hours: int = 24) -> int:
        """24時間以上放置されたworktreeを削除。"""

GasTownのアプローチ

• Witness: Rigごとの監視。ワーカー完了→次ステップへのルーティング、ヘルプ要求の分類
• Deacon: 全Rigを横断する監視デーモン。異常検知・メンテナンス派遣
• Mountain-Eater: 大規模タスクでワーカーが3回失敗したらそのIssueを自動スキップ

現行のAI Ops monitorに以下を追加:

現行のAI Ops monitorはVDU横断のプロセスとして動いているため、Deacon相当の機能は同じプロセスに追加する（別プロセスを立てるほどの規模ではない）。

• リソース偏り検知: 特定VDUがアカウントプールを占有していないか監視
• スタック検知: 一定時間（例: 30分）応答のないワーカーを検知→CEO通知
• VDU間調整: 月末に経理VDUの優先度を自動的に引き上げる等

GasTownのアプローチ

events.jsonlからsession_startイベントを収集し、claude --fork-session --resume <id>で前セッションのコンテキストを完全ロード。マルチアカウント間でもセッション共有可能。

• sessions.jsonでスレッドごとにセッションIDを保持し、--resumeで復元している
• しかし、異なるワーカー間でのセッション引き継ぎ（例: researcherの調査結果をcoderに渡す）は未対応
• アカウントが異なる場合、セッションIDが使えるか不明

GasTownのアプローチ

Bors方式のバッチマージ。ワーカーは直接mainにpushせず、merge-requestを作成。Refineryがバッチでrebase→テスト→成功ならfast-forward。失敗ならbisectで原因特定。

class MergeQueue:
    queue: list[MergeRequest]  # FIFO

    async def enqueue(task_id: str, branch: str) -> None:
        """worktreeブランチをマージキューに追加。"""

    async def process() -> None:
        """キュー先頭からrebase→テスト→マージを逐次実行。
        失敗したらそのMRをスキップし、次を処理。"""

● = 適用 / △ = 条件付き / — = 不要

GasTownで確認済みの実装パターン

残る検証項目

※ 旧v1.0の検証項目 #1（CLAUDE_CONFIG_DIR認証分離）と #4（複数プロセス干渉）はGasTown実装で確認済みのため削除。

Phase 0（マルチアカウント）
  ├──→ Phase 1（Scheduler強化）
  │      ├──→ Phase 2（worktree）──→ Phase 5（Refinery）
  │      └──→ Phase 3（監視強化）
  └──→ Phase 4（Seance強化）※検証項目#3に依存

Phase 2とPhase 3は並行して進められる。Phase 5はPhase 2の実績を見てから判断する。

そもそもの目的

GasTownを検討した動機は「完成されたオーケストレーションツールを使って、VDUをクイックに立ち上げる」こと。つまり、ゼロから作るより既製品を活用して時間を節約したかった。

しかし、前章（第3章）の結論は「案B: フルカスタム実装」であり、GasTownのコードは使わず「考え方だけ取り入れる」方針になっている。ここで問い直すべきは、設計思想を取り入れるために設計コストをかけること自体が、クイック立ち上げの目的と矛盾しないかという点。