CoW でつくる worktree で分離された並列環境

Claude Code などのエージェントを何本も並行で走らせるには、1 本ごとに依存・URL・Cookie・DB まで分かれた作業場所を、待たずに用意できる必要がある。git worktree に APFS の clonefile(CoW)・portless・sashiki を組み合わせて 1 コマンド数秒で作り、単一アプリと pnpm モノレポで実測した。git worktree・CoW・Cookie・リバースプロキシの仕組みを図で解説し、何本まで増やせるかの上限と、ポートの衝突でエラーにならずに別のエージェントの API と DB に接続してしまう問題と対策もまとめる。

TL;DR

  1. エージェントを並行で走らせる単位は git worktree。 ただし worktree はソースコードしか分けないので、node_modules・.env・port・Cookie・DB は自分で分ける必要がある
  2. node_modules は APFS の clonefile(CoW)で複製する。 125MB の node_modules が 1.2 秒で複製でき、空き容量はほぼ減らない。pnpm のモノレポでも、シンボリックリンクが相対パスなのでそのまま動く
  3. URL と Cookie は portless で分ける。 dev サーバーを portless run 経由で起動すると、worktree ごとに https://<ブランチ名>.<アプリ名>.localhost が割り当てられる。エージェントは自分の URL で動作を確かめられ、Cookie も混ざらない
  4. モノレポでは、web から同じ worktree の API を portless get で見つける。 アプリ名は web ではなく web.<project> のように明示する
  5. DB は sashiki でブランチごとに分ける。 worktree 1 つあたりの作成は約 3 秒
  6. 「無限」の上限はメモリで決まる。 web と API を動かす worktree 1 つで約 0.9GB 使った。64GB の Mac なら、ほかの用途を差し引いて数十本が目安
  7. portless のポート割り当てには TOCTOU の競合状態がある。 同時に起動した dev サーバーに同じポートが渡ることがあり(起動に時間がかかるアプリほど起きやすい)、tsx watch のように bind 失敗後も動き続けるものでは、片方の web がエラーにならずに別の worktree の API と DB に接続する。bind に失敗したら dev ごと止めるようにした

全体像

最初に、できあがる環境の全体を示します。エージェント 1 本につき worktree を 1 つ割り当て、依存・設定・URL・DB も worktree ごとに分けます。

DB(ブランチごと)共有しているものworktree(作業場所)エージェントエージェント Aエージェント Bエージェント Cfeat-aソースnode_modules・.envfeat-bソースnode_modules・.envfeat-cソースnode_modules・.env.gitコミットとブランチAPFS のデータブロックclonefile で共有portlesshttps://*.localhostの振り分けsashikiDB の baselinefeat-a の MySQLfeat-b の MySQLfeat-c の MySQL

実線が「worktree ごとに分かれているもの」、点線が「共有しているもの」です。共有しているものは、どれも書き込むと分かれるか、読むだけのものです。そのため、エージェント同士が互いの作業に影響しません。


なぜ作業場所を分けるのか

Claude Code などのコーディングエージェントは、1 つ指示すると数分から数十分ひとりで作業します。その間に別の作業を別のエージェントに任せられれば、人間は指示とレビューに専念できます。

エージェントを並行で走らせるには、1 本ごとに独立した作業場所が要ります。同じディレクトリで 2 本が動くと、片方の変更がもう片方のテストを壊します。

worktree を分けるエージェント Arepo.feat-login/エージェント Brepo.feat-payment/互いの変更に影響されない同じディレクトリで 2 本動かすエージェント Aログイン機能を修正中repo/エージェント B決済機能を修正中A の書きかけの変更でB のテストが落ちる

そこで使うのが git worktree です。ただし、worktree が分けるのは git が管理しているファイルだけです。新しい worktree を作った直後は次の状態になっています。

状態並行で動くエージェントにとって困ること
node_modules無い作業を始める前に毎回 install を待つ。ディスクも worktree の数だけ消費する
.env無い起動できない。手でコピーする必要がある
dev サーバーのポート全部 51732 本目以降が別のポートにずれ、エージェントがどの URL で確かめればよいか分からない
Cookielocalhost で共有Cookie はポートを区別しないので、片方のログイン状態がもう片方に混ざる
DB共有片方のマイグレーションやテストデータが、もう片方のエージェントの結果を変える

エージェントを好きなだけ増やすには、これらがすべて分かれた作業場所を、待たずに用意できる必要があります。ここでは 1 コマンド数秒で作れるようにします。

./scripts/wt-new.sh feat-a
# → ../<repo>.feat-a が数秒でできて、node_modules と .env が揃っている
cd ../<repo>.feat-a && npm run dev
# → https://feat-a.<app>.localhost で起動。ポートも Cookie も DB も他の worktree と独立

エージェントには、この worktree のディレクトリと URL を渡して作業させます。

以降、使う技術ごとに仕組みを説明してから、実際の作り方に入ります。


仕組み 1: git worktree

git の中身は 2 つに分かれている

git のリポジトリは、大きく 2 つに分かれています。

普通のリポジトリでは、作業ディレクトリは 1 つだけです。別のブランチで作業するには git switch で切り替える必要があり、同時に 2 つのブランチを開けません。

clone と worktree の違い

同時に 2 つのブランチを開く方法は 2 つあります。

git worktree add するrepo/main.git(履歴は 1 つだけ)repo.feat-a/feat-arepo.feat-b/feat-bgit clone を 2 回するrepo-1/.git(履歴を丸ごと持つ)repo-2/.git(履歴を丸ごと持つ)

worktree の実体

worktree のディレクトリにある .git は、ディレクトリではなく 1 行のファイルです。

$ cat ../worktree-lab.diagram/.git
gitdir: /Users/inouetaishi/gh/worktree-lab/.git/worktrees/worktree-lab.diagram

指している先には、その worktree 専用の情報が入っています。

repo/.git(本体)gitdir:共有共有worktrees/repo.feat-a/HEADどのブランチかindexステージした内容objects/コミットとファイルの中身refs/ブランチrepo.feat-a/.git(1 行のファイル)

1 つのブランチは、同時に 1 つの worktree でしか開けません。2 つ目で開こうとするとエラーになります。

$ git worktree add ../worktree-lab.d2 diagram-probe
fatal: 'diagram-probe' is already checked out at '/Users/inouetaishi/gh/worktree-lab.d1'

同じブランチを 2 か所で編集すると、どちらの変更が正しいか分からなくなるため、git がこの操作を拒否します。

worktree が分けないもの

git worktree add が作業ディレクトリに取り出すのは、git が管理しているファイルだけです。.gitignore に入っているものは取り出されません。

repo.feat-a/(作った直後)repo/(元)git が取り出す取り出されない取り出されないsrc/・package.json(git 管理)node_modules/(.gitignore).env(.gitignore)src/・package.jsonnode_modules/ が無い.env が無い

node_modules と .env は、自分で用意する必要があります。node_modules は install すれば作れますが、数十秒から数分かかり、ディスクも worktree の数だけ使います。これを一瞬で、ほぼディスクを使わずに用意するのが次の CoW です。


仕組み 2: CoW(copy-on-write)と clonefile

ファイルは「名前」と「中身のブロック」に分かれている

ファイルシステムの中で、1 つのファイルは次の 2 つでできています。

ディレクトリに並んでいるファイル名は、inode を指しています。

3 つのコピーのしかた

ファイルを「複製」する方法は 3 つあり、何を共有するかが違います。

clonefile(cp -c)a.jsinode 1ブロック X(共有)b.jsinode 2ハードリンク(ln)a.jsinode 1b.jsブロック X普通のコピー(cp)a.jsinode 1ブロック Xb.jsinode 2ブロック X'(中身を複製)
時間ディスク片方を書き換えると
普通のコピー中身の量に比例中身の分だけ増えるもう片方は変わらない
ハードリンク一瞬増えないもう片方も変わる(同じ inode なので)
clonefile一瞬増えないもう片方は変わらない

ハードリンクは速くて省容量ですが、同じファイルを 2 つの名前で呼んでいるだけです。片方の worktree で依存を書き換えると、もう片方も書き換わってしまいます。

clonefile は、inode は別々に作り、データブロックだけを共有します。速さと省容量はハードリンクと同じで、分離は普通のコピーと同じです。

書き込んだときに初めて分かれる

clonefile が別々のファイルとして振る舞えるのは、書き込んだブロックだけを新しく確保するからです。これを copy-on-write(CoW)と呼びます。

b.js に書き込むb.js の 2 番目を書き換えた後a.jsブロック 1ブロック 2ブロック 3b.jsブロック 2'(新しく確保)複製した直後a.jsブロック 1ブロック 2ブロック 3b.js

macOS の標準ファイルシステムである APFS は、このしくみを clonefile(2) というシステムコールで提供しています。cp に -c を付けると使えます。

cp -cR "$donor/node_modules" "$dst/node_modules"

node_modules は、作ったあとはほとんど書き換えません。そのため、何万ファイルあっても複製はほぼ一瞬で、ディスクもほぼ使いません。

ディスク使用量は du ではなく df で見る

CoW で複製したものの容量を測るときは注意が要ります。

ディスクから見るとファイルから見るとdonor/node_modules125MBfeat-a/node_modules125MB共有ブロック125MB 分du: ファイルごとに足す→ 250MBdf: ディスクの空きを見る→ 125MBしか使っていない

du はファイルごとのサイズを足すので、共有しているブロックを二重に数えます。実際に何バイト使ったかは、df で空き容量の差を見る必要があります。


仕組み 3: port・Cookie・reverse proxy

ブラウザは、Cookie をホスト名ごとに保存します。ポート番号は区別しません。

サブドメインで分けた場合https://feat-a.app.localhostCookie の保存先feat-a.app.localhosthttps://feat-b.app.localhostCookie の保存先feat-b.app.localhostポートで分けた場合http://localhost:5173(エージェント A)Cookie の保存先localhosthttp://localhost:5174(エージェント B)

ポートで分けると、A でログインした Cookie が B にも送られます。ログイン状態やセッションが混ざり、片方のエージェントの動作確認がもう片方の状態に左右されます。ホスト名(サブドメイン)を分ければ、Cookie の保存先も分かれます。

.localhost とリバースプロキシ

feat-a.app.localhost のような名前を使えるのは、.localhost で終わる名前が自分のマシン(127.0.0.1)を指す決まりになっているからです。Chrome と Firefox は、DNS に問い合わせずにそう解決します。

ただし、名前で分けても、届く先は同じ 127.0.0.1 です。どのアプリに渡すかを決めるのが リバースプロキシです。リクエストのホスト名を見て、対応するアプリのポートに転送します。

feat-b の dev サーバー127.0.0.1:4350feat-a の dev サーバー127.0.0.1:4795portless(127.0.0.1:443)ブラウザfeat-b の dev サーバー127.0.0.1:4350feat-a の dev サーバー127.0.0.1:4795portless(127.0.0.1:443)ブラウザホスト名 feat-a.app.localhost→ ルート表で 4795 番feat-b.app.localhost → 4350 番GET https://feat-a.app.localhost/(名前は 127.0.0.1 に解決)GET /200200GET https://feat-b.app.localhost/GET /200200

portless は、このリバースプロキシを開発用にまとめたツールです。

Caddy や nginx で同じことをするなら、ホスト名とポートの対応を設定ファイルに書いておく必要があります。portless は、起動したアプリが自分でルートを登録するので、worktree を増やしても設定を書き足す必要がありません。


構成

ここまでの仕組みを、次のように組み合わせます。

分けるもの方法
node_modulesAPFS の clonefile(cp -cR)で複製する。ロックファイルが元と違うときだけ install する
.env など git 管理外の設定cp -c で複製する
URL・port・Cookiedev サーバーを portless 経由で起動し、worktree ごとのサブドメインにする
DBsashiki でブランチ用の MySQL を作り、.env.local の DATABASE_URL を差し替える

題材は 2 つ用意しました。どちらも表示名を Cookie に保存する TODO アプリです。

worktree-monorepo-lab/
├── apps/
│   ├── web/        # React Router v8(SSR)。loader から API を呼ぶ
│   └── api/        # Hono + mysql2
├── packages/
│   └── shared/     # web と api で共有する型
└── scripts/
    ├── wt-new.sh
    └── wt-rm.sh

モノレポはルートの pnpm dev で web と api を並列に起動します。

{
  "scripts": {
    "dev": "pnpm -r --parallel --filter './apps/*' dev"
  }
}

--filter './apps/*' はクォートが必要です。クォートしないとシェルが glob を展開し、None of the selected packages has a "./apps/web" script で失敗します。

wt-new.sh がやること

はいいいえ同じ違うある無い./scripts/wt-new.sh feat-a複製元(メインのcheckout)でinstall が走っている?終わるまで待つ(時間切れならエラー)git worktree add../repo.feat-anode_modules をclonefile で複製(root・apps/*・packages/*).env などを cp -c で複製ロックファイルが複製元と同じ?sashiki がある?install して差分だけ埋めるブランチ用 DB を作り.env.local にDATABASE_URLURL を表示https://feat-a.app.localhost

以下、各段階を詳しく見ていきます。


node_modules: clonefile で複製する

cp -cR "$donor/node_modules" "$dst/node_modules"

複製したファイルは別の inode なので、片方の worktree で依存を追加・更新しても、もう片方には影響しません。

pnpm のモノレポでもそのまま複製できる

pnpm の node_modules は、ルートの node_modules/.pnpm に実体があり、各パッケージの node_modules からは シンボリックリンク(symbolic link。別の場所を指す特殊なファイル)で参照されます。

packages/node_modules/.pnpm/apps/web/node_modules/../../../node_modules/.pnpm/...../../../../packages/sharedreact@lab/sharedreact@19.3.1/node_modules/react(実体)shared/(実体)

シンボリックリンクはすべて相対パスです。node_modules/.modules.yaml に入っている絶対パスも、pnpm の共有ストアの場所(storeDir)だけでした。

相対パスなので、ルートと apps/*・packages/* の node_modules を同じ相対位置に複製すれば、複製先の中で正しく解決されます。

cp -cR で同じ相対位置にrepo.feat-a/(複製先)apps/web/node_modules/react.pnpm/react@19.3.1repo/(複製元)apps/web/node_modules/react.pnpm/react@19.3.1
for rel in node_modules apps/*/node_modules packages/*/node_modules; do
  cp -cR "$donor/$rel" "$dst/$rel"
done

.pnpm の中のファイルは pnpm のストアへのハードリンクですが、clonefile で複製すると別の inode になります。片方の worktree で pnpm --filter api add left-pad しても、メインと他の worktree には入りませんでした。

複製元を固定する

複製元(donor)はメインの checkout に固定しています。注意点は、donor で install が走っている最中に複製しないことです。書きかけの node_modules を複製すると、壊れた状態がそのままコピーされます。

スクリプトでは、install 系のコマンドを実行しているプロセスのうち、カレントディレクトリが donor のものを探して待ちます。

donor_installing() {
  local pid cwd
  for pid in $(pgrep -f '(npm|pnpm|yarn|bun)( [^ ]+)* (install|i|ci|add|remove|rm|update|up)( |$)' || true); do
    cwd=$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | sed -n 's/^n//p')
    [[ $cwd == "$donor" || $cwd == "$donor"/* ]] && return 0
  done
  return 1
}

ロックファイルが違うときだけ install する

worktree のブランチがメインと違う依存を持っていることもあります。複製したあとにロックファイルを比べ、違うときだけ install して差分を埋めます。

if ! cmp -s "$donor/$lockfile" "$dst/$lockfile"; then
  (cd "$dst" && "$pm" install)
fi

clonefile で複製した node_modules がすでにあるので、install はロックファイルの差分だけを入れます。1 パッケージ追加したブランチで、npm は 0.6 秒、pnpm は 0.4 秒でした。

node_modules/.vite(Vite の依存プリバンドル)も一緒に複製されるので、dev サーバーの初回起動も速くなります。逆に .react-router/(型生成の出力)は複製せず、各 worktree で生成させます。


package.json の dev を portless run 経由にするだけです。元のコマンドは dev:plain として残します。

{
  "scripts": {
    "dev": "portless run react-router dev",
    "dev:plain": "react-router dev"
  }
}

React Router(Vite)は環境変数 PORT を見ませんが、portless が --port と --host を自動で付けて起動します。

2 つの worktree で起動した状態はこうなります。

$ portless list
  https://wt-test-b.worktree-lab.localhost  ->  localhost:4350
  https://wt-test-a.worktree-lab.localhost  ->  localhost:4795

ブランチ名に / があるときは、最後のセグメントが使われます(feat/slash-check → slash-check.worktree-lab.localhost)。

A の URL で表示名を保存すると、Cookie は wt-test-a.worktree-lab.localhost に限定して保存され、B へのリクエストには付きませんでした(curl とブラウザの開発者ツールで確認)。

モノレポではアプリ名を明示する

portless は、名前を指定しないとパッケージ名から付けます。apps/web のパッケージ名が web だと https://web.localhost になり、他のプロジェクトの web とぶつかります。そこで、アプリごとに名前を明示します。

// apps/api/package.json
"dev": "portless run --name api.monorepo-lab tsx watch src/index.ts"

worktree の中では、これにブランチ名が付きます。

--nameweb.monorepo-labブランチ名wt-test-a--nameapi.monorepo-labhttps://wt-test-a.web.monorepo-lab.localhosthttps://wt-test-a.api.monorepo-lab.localhost

web から同じ worktree の API を見つける

web の loader は API をサーバー側で呼びます。このとき、自分と同じ worktree の API を呼ぶ必要があります。違う worktree の API を呼ぶと、違うエージェントの DB を読み書きすることになります。

portless get <name> は、portless run と同じ規則で URL を組み立てて出力します。worktree の中で実行すると、ブランチ名の付いた URL が返ります。

$ cd ../worktree-monorepo-lab.probe/apps/api
$ portless get api.monorepo-lab
https://probe.api.monorepo-lab.localhost

web の dev スクリプトで、これを環境変数に入れます。

// apps/web/package.json
"dev": "API_URL=${API_URL:-$(portless get api.monorepo-lab)} portless run --name web.monorepo-lab react-router dev"

1 回の画面表示で、リクエストは次のように流れます。

MySQL(feat-a)API(feat-a)web(feat-a)portlessブラウザMySQL(feat-a)API(feat-a)web(feat-a)portlessブラウザloader が API_URL を呼ぶAPI_URL = portless get の結果GET https://feat-a.web.monorepo-lab.localhost/GET /GET https://feat-a.api.monorepo-lab.localhost/todosGET /todosSELECT ...(DATABASE_URL は feat-a のブランチ)行JSONHTML

API は HTTPS で、portless のローカル CA で署名されています。portless は子プロセスに NODE_EXTRA_CA_CERTS を渡すので、web のサーバー側の fetch からもそのまま呼べました。

フロントとバックを別ブランチで動かす

モノレポでは、フロントエンドとバックエンドを別のブランチで動かしたいこともあります。たとえば、フロントエンドを feat-ui で作りながら、バックエンドは feat-api で作業中のものを使う場合です。

上の dev スクリプトは API_URL=${API_URL:-...} と書いているので、API_URL が指定されていればそれを使い、無ければ同じ worktree の API を使います。フロントエンド側の worktree では、web だけを起動し、API_URL でバックエンド側の API を指定します。

# バックエンド側: DB あり、web と API を起動
./scripts/wt-new.sh feat-api
cd ../worktree-monorepo-lab.feat-api && pnpm dev

# フロントエンド側: DB は使わないので WT_DB=0。web だけを起動する
WT_DB=0 ./scripts/wt-new.sh feat-ui
cd ../worktree-monorepo-lab.feat-ui
API_URL=https://feat-api.api.monorepo-lab.localhost pnpm --filter web dev
worktree feat-apiworktree feat-ui(DB なし)API_URL で指定API_URL 無し→ 同じ worktree の APIwebfeat-ui.web.monorepo-lab.localhostwebfeat-api.web.monorepo-lab.localhostAPIfeat-api.api.monorepo-lab.localhostfeat-api の MySQL

試したところ、feat-ui の web から追加した TODO は feat-api の API と DB に入り、feat-api の web にも表示されました。

シェルで API_URL を export したままにすると、どの worktree の web もその API に接続します。指定はコマンドの先頭に付けて、そのコマンドだけに効かせます。

初回起動はグローバルな設定を変える

portless は初回起動時に、ローカル CA を作ってシステムの信頼ストアに登録します。さらに、既定では 443 番ポートを使うため sudo で権限を昇格します。どちらもマシン全体に影響する変更なので、自分で実行して確認しました。

sudo のパスワードを入力できない状況では、1355 番ポートで起動します。その場合 URL に :1355 が付きます。


DB: sashiki でブランチごとに分ける

アプリが手元の MySQL に接続している場合、worktree を分けても DB は共有のままです。sashiki は、baseline(元になる DB の状態)からブランチ用の MySQL を秒単位で作るツールです。macOS では、ここでも APFS の clonefile を使います。

clonefileclonefileユーザー dev@feat-a127.0.0.1:28306ユーザー dev@feat-b127.0.0.1:28306baselineMySQLのデータディレクトリfeat-a のデータディレクトリfeat-b のデータディレクトリmysqld(feat-a 専用)mysqld(feat-b 専用)feat-a の APIsashiki のプロキシfeat-b の API

wt-new.sh の最後で、sashiki があればブランチ用の DB を作り、接続先を worktree の .env.local に書きます。

export SASHIKI_DB_HOST=127.0.0.1 SASHIKI_DB_PASSWORD=dev
sashiki create --exist-ok "$db_branch"
sashiki env "$db_branch" --url-var DATABASE_URL --db app --write "$dst/.env.local"

sashiki env --write は、.env.local の同じキーの行だけを置き換え、人が書いたほかの行は残します。書かれる内容は次のとおりです。

DB_HOST=127.0.0.1
DB_PORT=28306
DB_USER=dev@feat-a
DATABASE_URL=mysql://dev%40feat-a:dev@127.0.0.1:28306/app

ユーザー名の @ は %40 にエスケープされます。そのままだと、ドライバがホストとの区切りと読み違えるためです。この --url-var と --write は、今回の用途のために sashiki に足しました(sashiki の main に入っていて、次のリリースに含まれます)。

単一アプリでは、React Router の dev サーバーが .env と .env.local の両方を読むので、worktree ごとに接続先が切り替わります。

モノレポでは、DATABASE_URL をルートの .env.local に書き、API が起動時にルートの .env.local → .env の順に読みます。process.loadEnvFile はすでに設定されている環境変数を上書きしないので、先に読んだ .env.local が優先されます。

const root = resolve(import.meta.dirname, "../../..");
for (const f of [".env.local", ".env"]) {
  const p = resolve(root, f);
  if (existsSync(p)) process.loadEnvFile(p);
}

どちらの構成でも、A で追加した TODO は A にだけ、B で追加したものは B にだけ表示されました。

.env.local は .gitignore に入れておく必要があります。git 管理外の未追跡ファイルがあると、git worktree remove が --force なしでは消せなくなるためです。

DB は clonefile でも 1 つ約 113MB 増える

node_modules の複製はほぼ容量を使いませんが、DB は 1 つ約 113MB 増えました。CoW の図で言うと、mysqld が起動時にたくさんのブロックに書き込むからです。redo log、undo tablespace、ibtmp1 などが新しく書かれ、その分は共有されません。


問題: ポートの衝突で別の worktree の API に接続する

portless は、dev サーバーのポートを 4000〜4999 番からランダムに選びます。選んだ候補で一度 listen して空いていることを確かめ、閉じてから、そのポート番号を dev サーバーに渡します。dev サーバーはあらためてそのポートで listen します。

TOCTOU の競合状態

この「確認してから使う」流れには、確認と使用の間に別のプロセスが同じポートを使うと衝突する、TOCTOU(time-of-check to time-of-use)の競合状態があります。2 つの dev サーバーを同時に起動し、たまたま同じ候補を引くと、次のようになります。

B の dev サーバーA の dev サーバーportless(B)portless(A)B の dev サーバーA の dev サーバーportless(B)portless(A)まだどちらも listen していないので両方とも「空き」4388 番を確認 → 空き(閉じる)4388 番を確認 → 空き(閉じる)PORT=4388PORT=4388127.0.0.1:4388 で listenEADDRINUSE

portless 0.15.12 で、Math.random を差し替えて 2 つに同じ候補を引かせると、両方に同じポートが渡り、後の方が EADDRINUSE になりました。衝突が起きうるのは、確認してから dev サーバーが bind するまでの間です。この間は一瞬ではなく、dev サーバーの起動時間まるごとです。起動に何秒もかかるアプリをいくつも同時に起動すると、衝突は珍しくありません。issue #533 には、ほかの利用者から次の実測が報告されています(8 つを並列に起動)。

bind までの時間衝突した回数
0 秒200 回中 0 回
3 秒20 回中 1 回
8 秒12 回中 1 回
15 秒12 回中 2 回

turbo で 8 アプリのモノレポを起動したところ、4 回続けて衝突したという報告もあります。この競合状態は、portless の現行版(0.15.13)では解決していません。修正の PR(#541)は出ていますが、まだマージされていません。

衝突すると何が起きるか

衝突したときの挙動は、dev サーバーによって違います。

dev サーバー衝突したとき
Vite(React Router)portless が --strictPort を付けて起動するので、Vite がエラーで終了する
tsx watchbind に失敗しても変更待ちで動き続ける。portless のルートが残り、エラーにならずに別の worktree のアプリに接続する

tsx watch の場合を順に示します。検証中に、2 つの worktree の API に同じポートが割り当てられたとき、実際にこの状態になりました。

https://wt-test-a.api.monorepo-lab.localhost  ->  localhost:4138
https://wt-test-b.api.monorepo-lab.localhost  ->  localhost:4138
B の webB の API(tsx watch)portless(B の API)A の APIportless(A の API)B の webB の API(tsx watch)portless(B の API)A の APIportless(A の API)tsx watch は「変更待ち」で動き続ける子プロセスが生きているのでルート B → 4138 番を残すB の web が A の API と A の DB をエラー無しで読み書きするPORT=4138 で起動127.0.0.1:4138 で listenPORT=4138 で起動EADDRINUSE(bind 失敗)B の API を呼ぶ4138 番に転送 = A の API

B の web は A の API を呼び、A の DB を読み書きしていました。 画面にもログにもエラーは出ません。エージェントを並行で走らせている場面なら、B のエージェントが A のエージェントの DB を書き換えることになります。

単一アプリ版は Vite だけなので、衝突しても起動に失敗するだけで済みます。node --watch や nodemon も、クラッシュ後に変更待ちに入る点は tsx watch と同じなので、同じ問題が起きるはずです(こちらは試していません)。

対策: bind に失敗したら親ごと止める

API で bind の失敗を受け取ったら、親の tsx watch ごと止めるようにしました。portless の子プロセスが終了するので、portless もルートを外して終了します。

API: bind 失敗EADDRINUSE親の tsx watch にSIGTERM を送るtsx watch 終了portless が子の終了を検知→ ルートを外して終了dev がエラーで終了する(別の API には接続しない)
server.on("error", (err: NodeJS.ErrnoException) => {
  console.error(`api: ${port} 番を使えない(${err.code})。dev を止める`);
  if (process.env.PORTLESS_URL) process.kill(process.ppid, "SIGTERM");
  process.exit(1);
});

わざと衝突させて確かめました。127.0.0.1:4777 を別プロセスで使用中にし、PORTLESS_APP_PORT=4777 で API を起動すると、API が止まり(exit=1)、portless のルートも tsx watch のプロセスも残りませんでした。

これはエラーで止まるようにするだけで、衝突そのものは防げません。止まったらもう一度起動すれば、別のポートが選ばれます。


何本まで増やせるか

「無限に」と言っても、実際には上限があります。モノレポ(web と API)の worktree を 1 つ起動して、使う資源を測りました。

worktree 1 つ(web + API + DB)pnpm と portless のラッパーtsx・Vite・esbuildmysqldディスクほぼ DB の分メモリ 約 790MB(dev 一式)メモリ 約 130MB約 113MB
資源worktree 1 つあたり上限を決めるもの
メモリ(dev サーバー一式)約 790MBpnpm と portless のラッパー、tsx、Vite(esbuild を含む)の RSS の合計
メモリ(mysqld)約 130MBsashiki のブランチ 1 つ
ディスク約 113MBほぼ DB の分。node_modules はほぼ 0
ポート2 つportless の割り当て範囲は 4000〜4999 の 1000 個
DB のブランチ数1 つsashiki の設定 max_branches(この環境では 20)

RSS(プロセスが使っている物理メモリ)の合計は、複数のプロセスで共有しているページを重複して数えるので、実際の使用量はこれより少なめです。それでも目安として、1 本あたり約 0.9GB です。64GB の Mac で、OS やエディタ、エージェント本体の分を差し引くと、数十本が現実的な上限です。

先に上限に達しやすいのは、メモリよりも設定の上限です。sashiki の max_branches はこの環境では 20 なので、それ以上並べるなら設定を上げます。DB を使わない作業なら WT_DB=0 で作れば、DB の分の資源は要りません。

また、dev サーバーは常に動かしておく必要はありません。エージェントが動作を確かめるときだけ npm run dev で起動し、終わったら止めれば、同時に動くのは確認中の数本だけになります。


実測

macOS 26.5.1 です。node_modules は単一アプリが 125MB、モノレポのルートが 132MB です。

項目単一アプリ(npm)モノレポ(pnpm)
wt-new.sh の作成時間2.4〜3.3 秒3.2〜4.7 秒
installロックファイルが同じなら走らない。差分 1 パッケージで 0.6 秒同じく走らない。差分 1 パッケージで 0.4 秒
URL2 つとも 200web・api の 4 つとも 200

作成時間の大半は sashiki の DB 作成です。

項目結果
node_modules の複製(clonefile)1.2 秒。空き容量の差は ±6MB で、何もしないときの変動と同程度
node_modules の複製(cp -R)3.6 秒。125MB を消費する
sashiki のブランチ 1 つ約 113MB

ディスクの消費は、前述のとおり du ではなく df の空き容量の差で見ています。


macOS で起きたその他の問題

pgrep に -E が無い

Linux の pgrep に合わせて pgrep -f -E と書いたら、macOS では illegal option -- E で落ちました。macOS の pgrep は最初から拡張正規表現で解釈するので、-E は不要です。

bash 3.2 で "$dst(" が unbound になる

macOS の /usr/bin/env bash は、標準では bash 3.2 です。次の行が dst�: unbound variable で落ちました。

echo "[wt-rm] removed: $dst(ブランチ $branch は残している)"

bash 3.2 は、変数名の直後に全角文字があると、そのバイト列を変数名の一部として読みます。set -u なので、存在しない変数として止まります。${dst} のように波括弧で囲むと直ります。

日本語のメッセージを書くシェルスクリプトでは、変数の直後に全角文字が来る箇所を全部 ${…} にしておくのが安全です。

sashiki env のホスト名が解決できない

sashiki env は DB_HOST=sashiki.local を返しますが、この名前は解決できませんでした。手元ではプロキシが 127.0.0.1 で listen しているので、127.0.0.1 で接続しています。


既存の worktree ツールと組み合わせる

worktree を作って node_modules などを CoW で複製する部分は、既存のツールにもあります。たとえば次の 2 つは、作成後に任意のコマンドを実行できます(README で確認した範囲)。

ツールCoW での複製作成後のコマンド
wtx(旧 wt-cli)APFS・btrfs・XFS では reflink で複製し、それ以外は通常のコピーにする.worktree.yml の setup。WTX_BRANCH_NAME などの環境変数が渡る
rabi(旧 phantom)README からは確認できなかった作成後と削除前の hook

アプリごとに違うのは、DB と URL の部分です。既存のツールを使う場合も、作成後のコマンドから sashiki create と sashiki env --write を呼べば、ブランチ用の DB の接続先を worktree の .env.local に書けます。URL は、各アプリの dev スクリプトを portless run 経由にするだけです。


使い終わったら

./scripts/wt-rm.sh feat-a
ある無い./scripts/wt-rm.sh feat-a未コミットの変更がある?git worktree removeがエラー(--force は付けない)worktree を消すsashiki のブランチ DBを消すgit のブランチは残す(消すかは人間が決める)

未コミットの変更がある worktree では git worktree remove がエラーになるので、--force は付けていません。エージェントの作業を誤って消さないためです。git のブランチも消しません。消すかどうかは人間が決めます。


まとめ

← Back to all posts