Agent Branch エージェント・ブランチ

解決する課題 #

エージェントは機械の速さで間違えますが、共有データには「試して、差分を見て、レビューして、元に戻す」手段がありません。並行して動くエージェント同士が、互いの作業を踏みつけることもあります。

2026 年 4 月の事故では、あるエージェントが権限の広すぎるトークンを使い、本番のボリュームと、同じボリュームにあったバックアップを 9 秒で削除しました。書き込めるのがブランチだけで、削除がソフトで、スナップショットがその権限の外にあれば、被害ははるかに小さく済んだはずです。

仕組み #

• ブランチは安価です（エンジンによりますが、理想的には O(1) に近いコスト）。リースが許すのは、ブランチの中への 書き込みと、ターゲットへの propose です。
• 保護ツリー。 メインラインはマージでしか更新できません。認証情報が漏れても、そこへ直接は書き込めません。
• Agent PR。 差分、意図、出どころ（読み取りマニフェストの要約）、チェック結果、ラベルの要約を伴います。チェックに通り、ポリシーが許せば自動でマージされ、そうでなければ Human Gate に回ります。
• ソフト削除。 保護ツリーでの削除は回収エリアに移り、既定で 7 日間保持されます。スナップショットは所有者のもので、どのリースの権限も及びません。
• チェックポイント。 名前つきのスナップショット。restore でファイルをチェックポイントまで戻せます。
• マージ。 テキストは 3 方向マージ、それ以外のファイルはファイル単位でマージします。競合したら止まり、黙って上書きすることはありません。構造化データには、登録されたマージャーか、人間が必要です。
• TTL とクォータ。 ブランチの爆発を防ぎます。
• 並行の試行。 1 つのタスクに N 本のブランチを開き、最良のものをマージして、残りは回収します。

小さく始める #

• Git のブランチと worktree に、Forgejo、Gitea、GitHub の 保護されたメイン を組み合わせます。
• 大きなディレクトリには btrfs や ZFS のスナップショットとクローン、オブジェクトストレージには Tigris や lakeFS のフォークを使います。
• まず「削除は回収エリアへ」と「スナップショットは所有者のもの」を正しく実現します。最も安く済み、最も多くの被害を防げます。

インターフェースのスケッチ #

説明用の例です。フィールド名は仕様 v0.3 までに変わる可能性があります。

nas branch create cleo/release-notes --from main --ttl 48h
nas checkpoint create before-refactor
nas propose --into main --checks links,schema
nas restore before-refactor
nas trash list                    # recycle area, kept 7 days by default
nas trash restore <path>

仕様が求めること #

• 保護ツリーは、マージによってのみ更新できなければならない。どの認証情報も、直接書き込んではならない。
• マージは、出どころ（実行、リース、プリンシパル）を持つコミットを生成しなければならない。
• スナップショットやバックアップの削除を許すリースがあってはならない。
• 保護ツリーでの削除はソフトでなければならず、設定された期間（既定では 7 日間）内なら復元できなければならない。
• 競合を黙って解決してはならない。マージは止まって報告しなければならない。
• ブランチには TTL とクォータがなければならない。

借りたものと、新しいもの #

以下はすべて確立された慣行です。新しいのは、 ブランチを 実行とリース に結びつけることで、ブランチが認可の単位、マージがレビューの単位になる点です。ブランチやスナップショットそのものは新しくありません。

• Git worktree
• lakeFS for agents
• Tigris Agent Kit
• Cloudflare Artifacts

正直な限界 #

• ブランチが守るのは NAS の内側のデータだけです。外部への副作用は元に戻せません。すでに送ったメールや、すでに呼び出した API などです。
• 大きなバイナリファイルやデータベースファイルは、マージが困難です。
• レビュー疲れは起こりえます。そのため、低リスクのパスは自動でマージしてよいことにして、承認率を計測します。

未解決の問い #

• セマンティックなマージャーは、どう登録し、どう信頼するのか。
• バイナリの競合に対するやり取りは、どうあるべきか。

よくある質問 #

関連するコンセプト #

• Human Gate (ヒューマン・ゲート) 元に戻せない、外へ出る、権限を広げる操作の前にだけ現れ、実際の差分を見せます。
• Agent Home (エージェント・ホーム) ロールごとのディレクトリ。履歴つきで、普通のファイルのまま持ち出せます。
• Flight Recorder (フライトレコーダー) 実行ごとに、ハッシュでつながれた記録を残します。実行が何を読んだかも含みます。