dev

dev — Lab-Stack の起動

1つのコマンドで、Vercel-Labs 風の開発ループを構成する4つの要素を起動します。

1. portless → 名前付き HTTPS https://<branch>.localhost（worktree 間でポートが競合しません）
2. emulate → @emulators/adapter-next を介して、同じオリジン上でステートフルな API エミュレーターを起動します
3. 開発サーバー → pnpm dev / npm run dev / yarn dev（自動検出）
4. agent-browser → ブランチ名を付けた、あらかじめウォームアップ済みのセッション

状態は .claude/state/dev-stack.json に保存されます。終了時に dev stop は PID を読み込み、起動順とは逆の順序で SIGTERM を送信します。

expect と連携します： dev がウォームアップする agent-browser セッションは、expect（および M125 #2 の自動トリガー）が接続するものと同じです。そのため、最初の UI テストで起動待ちが二度発生することはありません。

実行するタイミング

状況	コマンド
新しいブランチで作業を開始する	dev
セッション中断後に再開する	dev（冪等です。すでに稼働中のプロセスはスキップします）
ブランチを削除する前に終了する	dev stop
状態を確認する	dev status
プレビューを関係者と共有する	dev --share（tailnet）または dev --funnel（公開）
時間制限付きのライブデモ	dev --live 4（公開ファネル、有効期限は4時間）

バックグラウンド化した開発セッションの再開（CC 2.1.144+）： claude --bg で開始したセッションが、インタラクティブなセッションとともに /resume に bg と表示されるようになりました。クラッシュやセッション終了後の直接的な復旧手段として、エージェントビューに移動する代わりに /resume を使用してください。

バックグラウンドシェルセッション（CC 2.1.154+）： claude agents で ! <command> と入力すると、接続と切断が可能なバックグラウンドセッションとしてシェルコマンドを実行できます。claude --bg --exec '<command>' でも使用できます。ターミナルを占有せずに監視したい、ウォッチャー、ビルド、サーバーなどの長時間実行する開発ループのプロセスに便利です。

モード（M127）

フラグ	ラップするもの	接続範囲	Tailscale CLI
（なし）	portless <slug> <pkg-mgr> run dev	https://<branch>.localhost のみ	不要
--share	portless --tailscale ...	https://*.ts.net 経由のtailnetメンバー	必須
--funnel	portless --funnel ...	インターネット上に公開	必須
--live N	portless --funnel ... + N時間後に有効期限切れ	公開、live-demos.jsonl で追跡	必須

Tailscale は任意です。--share／--funnel／--live を指定した場合にのみ必要です。共有しないユーザーには、デフォルトの dev の動作に変更はありません。

turbo.json または package.json のワークスペースが検出されると（#1562）、起動時には 設定不要の portless が使用されます。各ワークスペースの開発スクリプトを自動検出し、タスクグラフを使ってサブドメインを割り当てます。状態ファイルには mode: "monorepo" と表示されます。 portless list または dev status でサブドメインを確認できます。

起動シーケンス

portless はサイドカーではなくラッパーです。portless <slug> <pkg-mgr> run dev は開発サーバーのライフサイクルを管理する、1つに統合されたコマンドです。boot.sh はラッパーの PID を追跡し、stop.sh はプロセスツリーをたどって子プロセスをクリーンアップします。

0. Detect package manager      pnpm > yarn > bun > npm   (lockfile-based)
1. Resolve subdomain slug      <branch> → lower → / to - → DNS-safe → ≤63 chars
2. portless proxy start         (idempotent — skipped if `portless list` already responds)
3. emulate --seed <yaml>        (sidecar, optional — only if emulate.config.yaml exists)
4. portless <slug> <pkg-mgr> run dev   (FUSED — wrapper owns dev server's lifecycle)
5. portless get <slug>          (poll up to 30s for the route to register)
6. wait-on <baseUrl>            (poll up to 30s for the dev server through the proxy)
7. AGENT_BROWSER_SESSION=<slug> agent-browser open <baseUrl>   (warm + register session)
8. atomic state write           (.claude/state/dev-stack.json via jq + temp + mv)
9. print summary

注釈付きの詳しい解説：references/boot-sequence.md。

状態ファイルの形式

{
  "bootedAt": "2026-04-27T12:34:56Z",
  "branch": "feat/m125-lane-b",
  "subdomain": "feat-m125-lane-b.localhost",
  "baseUrl": "https://feat-m125-lane-b.localhost",
  "mode": "single",
  "processes": {
    "portlessWrapper": {
      "pid": 86104,
      "command": "portless feat-m125-lane-b pnpm run dev"
    },
    "agentBrowser": { "sessionName": "feat-m125-lane-b" },
    "emulate":      { "pid": 86200, "command": "emulate --seed emulate.config.yaml" }
  },
  "emulators": ["github", "stripe"],
  "share": null,
  "notes": "portless proxy daemon is shared and not tracked here — stop.sh leaves it running."
}

--share／--funnel／--live を使用すると（M127 #1561 / #1565）、share は次のようになります。

"share": {
  "mode": "tailscale",
  "tailscaleUrl": "https://app.your-tailnet.ts.net",
  "expiresAt": "2026-05-03T20:00:00Z"
}

mode は "single"（デフォルト）または "monorepo"（turbo.json／ワークスペースを検出した場合）です。portless と devServer ではなく portlessWrapper である点に注意してください。portless が開発サーバーを管理します。完全なスキーマは references/state-schema.md を参照してください。

自動表示されるヒント（M127）

dev の起動時に package.json を調べ、ヒントを表示します。

• @json-render/* を検出（#1560）→ 開発時にインスペクターパネル（Spec / State / Actions / Stream / Catalog / Pick）を有効にするための、devtools アダプターのインポート行を表示します。本番ビルドではツリーシェイクされます。
• @clerk/* を検出（#1563）→ emulate.config.yaml に clerk がある場合は、モックログイン URL（http://localhost:4012）を表示します。ない場合は、emulate-seed --auto の実行を促す警告を表示します。

前提条件と正常な no-op

$ dev
✓ portless     found
✓ agent-browser     found
✓ jq     found
[1] slug       feat-m125-lane-b

# OR with a missing prereq:
✗ portless not found.   Install: npm i -g portless

Skipping boot — install missing tools and re-run.

portless、agent-browser、および jq が必要です。emulate は任意です。emulate.config.yaml が存在する場合にのみ必要です。起動は必須項目がすべてそろっていることを条件とし、emulate 設定がない場合は、エミュレーターなしで起動を続行します。

CI=1 の場合は起動を短絡し、直ちに終了コード 0 で終了します。

ステータスと終了処理

$ dev status
ork:dev — feat/m125-lane-b
  ✓ portlessWrapper    portless feat-m125-lane-b pnpm run dev
  ✓ agentBrowser       feat-m125-lane-b
  base url:  https://feat-m125-lane-b.localhost
  booted:    2026-04-27T19:36:54Z
  portless:  route registered ✓

$ dev stop
ork:dev — sending SIGTERM in reverse boot order…
  ✓ agent-browser session "feat-m125-lane-b" closed
  ✓ portless wrapper (pid 86104) + 21 descendant(s) stopped
Cleared .claude/state/dev-stack.json

Note: portless proxy daemon left running (shared). Run `portless proxy stop` if you really mean to stop the daemon.

停止時は、ラッパーのプロセスツリー（pgrep -P で再帰的に取得）をたどり、末端のプロセスから順に SIGTERM を送信します。portless はシグナルを常に適切に伝播するとは限らないためです。portless プロキシデーモン自体は共有インフラストラクチャであり、dev stop によって終了されることはありません。

ワークツリーの動作

各 Git ワークツリーにはそれぞれ独自のサブドメインが割り当てられます。たとえば、同じマシン上で feat-foo.localhost と feat-bar.localhost を共存させられます。状態ファイルは各ワークツリーの .claude/state/ 内にあるため、あるワークツリーで実行した dev から、別のワークツリーのプロセスが見えることはありません。

冪等性

スタックがすでに起動している状態で dev を再実行しても、何も行いません。

$ dev
ork:dev — feat/m125-lane-b already running.
  https://feat-m125-lane-b.localhost  (uptime 2h 14m)
Run dev stop to tear down, or dev status for detail.

稼働確認では、追跡対象の各 PID に対して process.kill(pid, 0) を実行します。停止しているプロセスがある場合、スキルはそのプロセスを表示し、状態のクリーンアップと再起動を提案します。

agent-browser の構成方法

セッション名はサブドメインと同じです。そのセッションを対象とする agent-browser コマンドは、接続中のセッションがそれだけであれば --session フラグを必要としません。

agent-browser open "https://feat-m125-lane-b.localhost/dashboard"
# implicit session = "feat-m125-lane-b" because it's the only one

expect（M125 #2）は dev-stack の状態ファイルを読み取り、この同じセッションを再利用するため、2 回目のハンドシェイクは不要です。

expect との統合（M125 #2）

.tsx の編集後に auto-expect が実行されると、次の処理を行います。

1. .claude/state/dev-stack.json を読み取り、agent-browser のセッションとベース URL を特定します。
2. ファイルパスから対象のルートを算出します（app/dashboard/page.tsx → /dashboard）。
3. 稼働中のセッションを使い、<baseUrl><route> に対して agent-browser を操作します。
4. ARIA スナップショットを (route, parentCommit) をキーとしてメモリに記録します（M125 #6）。

dev スタックが起動していない場合、auto-expect は何も表示せずにスキップします。必須の依存関係ではなく、前提条件は dev です。

使用しない場合

• CI — CI=1 を設定してください。起動せずに終了コード 0 で終了します。
• 本番環境へのデプロイ — 使用しないでください。開発ループ専用です。
• Vercel-Labs 以外のスタック — インストール方法のヒントが表示されます。基盤となるツールは引き続き手動で実行できます。
• tmux -CC セッション内 — agent-browser ダッシュボードは iTerm2 の tmux 統合と互換性がありません。

スクリプト

スクリプト	処理内容
scripts/boot.sh	前提条件をすべて確認してから、9 ステップで起動します。冪等性があり、すでに起動している場合は何も行いません。CI では CI=1 を検出してスキップします。
scripts/stop.sh	起動時と逆の順序で SIGTERM を送信し、5 秒後に SIGKILL によるフォールバックを行います。最後に状態ファイルを削除します。
scripts/status.sh	見やすい形式でステータスを表示します。稼働確認のみを行うには --quiet を指定します（稼働中なら終了コード 0、停止中なら 1）。起動時の冪等性確認に使用されます。

dev は scripts/boot.sh を、stop は stop.sh を、status は status.sh を呼び出します。正となる情報源はシェルスクリプトです。

参考資料

ファイル	用途
references/boot-sequence.md	コマンド付きの起動手順
references/state-schema.md	JSON の全構造と各フィールドの意味

ルール

ルール	影響度	適用されるタイミング
rules/lab-stack-prerequisites.md	CRITICAL	毎回の起動
rules/branch-named-subdomain.md	HIGH	サブドメインの解決時
rules/idempotent-boot.md	HIGH	起動中の再実行時
rules/teardown-order.md	MEDIUM	stop の実行時

/goal で無人実行する

/goal（CC 2.1.139 以降）で完了条件を設定すると、このスキルは条件が満たされるまでターンをまたいで処理を続けます。対話形式、-p、Remote Control で動作します。オーバーレイパネルには、経過時間、ターン数、トークン数がリアルタイムで表示されます。

このスキルの完了条件の例：

/goal until services.running == 4, or stop after 5 turns

停止条件：4 つの開発ループサービス（portless、emulate、dev-server、agent-browser）が、それぞれのポートまたはソケットで正常であると報告したとき。claude.ai Remote Control の実行と互換性があります。

関連スキル

• expect — 差分を考慮したブラウザーテストです。このスキルがウォームアップする agent-browser セッションを再利用します
• emulate-seed — ステップ 3 で使用するエミュレーター設定を生成します
• portless（スキル）— 基盤となるツールのドキュメントです
• browser-tools（スキル）— agent-browser のコマンドリファレンスです