paperclip-dev-workspace-run-verify-fix

Paperclip 開発ワークスペースの起動／検証／修正

このスキルは、プロジェクト実行ワークスペースのランタイムサービスを通じてサービスを起動する、Paperclip 固有の開発ワークスペースを対象とします。通常は、paperclip-dev などの worktree サービスを使用します。

以下のすべてを満たしたとき、成功とみなします。

• サービスが通常の管理対象ランタイム経路を通じて起動されており、デタッチされた回避策を使っていない
• worktree データベースが、プライマリインスタンスのデータベースから完全にブートストラップされた分離クローンである
• /api/health が status: ok と bootstrapStatus: ready を返す
• ルートページが 200 を返し、最初の管理者向けセットアップ画面が表示されない
• ボードユーザーが通常の開発用認証情報でログインできる
• アプリに、手動でコピーした認証ユーザーだけではなく、クローンされたデータが適切に表示される
• メインコントロールプレーンで、サービスが想定 URL とともに running／healthy と表示される
• 提供されているワークスペースアプリでも、そのサービスが認識され、running／healthy と表示される
• サービスポートを所有するプロセスが対象ワークスペースに実際に属している。readlink /proc/<pid>/cwd の結果が対象 worktree 内を指し、兄弟ワークスペース内を指していない

どれか一つでも満たさない場合は、修正を続けてください。プローブが一つ成功しただけで、問題を完了扱いにしないでください。

厳守事項

• マスターのチェックアウト /srv/paperclip/home/paperclipai/paperclip（実際のインスタンス .env があるプライマリリポジトリ）は、ワークスペース修復の対象にしてはいけません。worktree ランタイムサービスの接続先に指定したり、そこまたは <master>/.paperclip/worktrees/ 配下に git worktree add したり、ワークスペースの修復中にその .env を編集したりしないでください。管理対象ワークスペースは、それぞれ専用のフォルダーで実行されます。例：~/.paperclip-worktrees/instances/<slug>/…
• running／healthy のランタイム行や、成功した /api/health だけを信用してはいけません。service:paperclip-dev のポートはサービス設定で固定されているため、兄弟ワークスペースのプロセスがそのポートを所有したまま、ヘルスチェックに応答することがあります。修正の前後に必ず、ポート所有者の実際の cwd（readlink /proc/<pid>/cwd）を確認してください。ポート引き継ぎによって、ランタイム行に記録された cwd と pid が偽装される場合があります。
• Paperclip CLI、開発サーバー、worktree、データベース、ビルド、またはテストのコマンドを実行する前に、doc/DEVELOPING.md を読んでください。
• worktree とデータベースの操作では、信頼できる情報源として Paperclip CLI と API を使用してください。通常の修正手順で psql、埋め込み Postgres の直接コマンド、または場当たり的な行コピーを使用しないでください。
• 最終的な修正として認証行だけを手動でコピーしないでください。それでログインは確認できますが、分離されたワークスペースに完全にブートストラップされたデータベースがあることは確認できません。
• 再利用可能なワークスペースサービスに関するタスクでは、pnpm dev やデタッチされたシェルプロセスよりも、管理対象ランタイムの起動／停止ルートを優先してください。
• 破壊的な Git 操作やデータベース操作は避けてください。worktree 内のユーザー変更を保持してください。
• 修正を証明できる、最小限の検証を実施してください。コードを変更した場合に限り、対象を絞ったテストを追加してください。
• 根本原因、具体的な修正内容、検証結果、コミットへのリンクがあればそれを含めて、課題にコメントを残してください。最終ステータスを明確に設定してください。

収集する入力

利用可能な場合は環境変数を使用してください。API キーやパスワードを出力しないでください。

• PAPERCLIP_API_URL：メインコントロールプレーンの API URL
• PAPERCLIP_API_KEY：エージェント API キー
• PAPERCLIP_RUN_ID：ランタイムサービスの変更に使用する現在の実行 ID
• PAPERCLIP_TASK_ID：現在の課題 ID
• PAPERCLIP_COMPANY_ID：会社 ID
• PAPERCLIP_AGENT_ID：現在のエージェント ID
• worktree サービスの実行ワークスペース ID
• ランタイムワークスペースのコマンド ID。通常は service:paperclip-dev
• サービスの想定 URL。例：http://paperclip-dev:40631
• 開発用認証情報の所有者（ユーザーから提示されている場合）。パスワードは決して投稿しないでください

実行ワークスペース ID またはサービスコマンド ID が不明な場合は、まず課題、プロジェクト、または実行ワークスペースの API レコードを確認してください。推測でランダムなポートに管理対象外のサーバーを起動しないでください。

通常の実行シーケンス

ユーザーからワークスペースの起動、再起動、または新たに準備が整った状態にする必要があるワークスペースの修復を依頼された場合に使用します。

1. 最新のイシューコメントを確認し、成功条件を自分の言葉で言い換えます。
2. メインのコントロールプレーンから現在のランタイム状態を確認します。
3. 対象のポートに競合がないか確認します。現在のポート所有者とその実際の cwd を特定し、同じポートを使用している別のワークスペースのランタイム行がないか確認します（「ポートの競合とワークスペースの識別」を参照）。
4. 別の稼働中のワークスペースまたはエージェントの実行がそのポートを使用している場合は、管理された制御経路を通じてその所有者を停止し、ポートが空いた状態を維持していることを確認します。対象を再起動する前にこれを行ってください。そうしないと、その所有者が再起動してポートを再取得する可能性があります。
5. 対象のランタイムサービスの管理対象インスタンスをすべて停止します。
6. データベースが完全かどうか疑わしい場合は、プライマリインスタンスから完全なクローンでワークツリーを再シードします。
7. 管理されたランタイム API を通じてランタイムサービスを起動します。
8. メインのコントロールプレーンと、提供されているワークスペースアプリの両方から、ヘルス、ブートストラップ状態、ログイン準備状況、データの投入状況、ランタイムの可視性、ポート所有者の識別情報を確認します。
9. 確認項目に失敗した場合は、その失敗を正確に診断し、最も範囲の狭い修復手順に戻ります。
10. イシューにコメントし、最終的な対応状況を設定します。

管理された起動／停止

メインのコントロールプレーン上のランタイムサービスのエンドポイントを使用します。変更が現在のハートビートに関連付けられるよう、X-Paperclip-Run-Id を含めてください。

curl -sS -X POST \
  "$PAPERCLIP_API_URL/api/execution-workspaces/$EXECUTION_WORKSPACE_ID/runtime-services/stop" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  --data-binary '{"workspaceCommandId":"service:paperclip-dev"}'

curl -sS -X POST \
  "$PAPERCLIP_API_URL/api/execution-workspaces/$EXECUTION_WORKSPACE_ID/runtime-services/start" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  --data-binary '{"workspaceCommandId":"service:paperclip-dev"}'

API が既存のサービスを返した場合は、候補としてのみ扱ってください。信頼する前に、実際の /api/health とそのポート所有者の識別情報を確認してください。

ポートの競合とワークスペースの識別

service:paperclip-dev はサービス設定で明示的なポートを固定するため、そのサービスを起動するすべてのワークスペースが同じポートを要求します。起動時、コマンドラインが似ているプロセスがすでにポートを使用している場合、サービスの引き継ぎによってそのプロセスが引き継がれます。その際、所有者の実際の cwd ではなく、要求された cwd が記録されます。この結果、次の2つの問題が発生します。

• 複数のワークスペースが、プロセスは1つしか存在しないのに、同じポートについて running の行を保持することがあります。どのワークスペースの URL を開いても、同じプロセスに接続されます
• ランタイム行の cwd、pid、ヘルス状態がすべて正しく見えても、URL が実際には隣接するワークツリーのアプリを提供していることがあります

識別の確認 — 既存のサービスを信頼する前、および起動または再起動のたびに、これを実行してください。

pid=$(lsof -nP -iTCP:"$SERVICE_PORT" -sTCP:LISTEN -t | head -1)
readlink "/proc/$pid/cwd"

解決された cwd は、対象のワークツリー内にある必要があります（開発サーバーは通常 <worktree>/server で実行されます）。信頼できる情報源は /proc/<pid>/cwd だけです。ランタイム行の cwd フィールド、ルートへの 200、または正常な /api/health を、識別の証明として受け入れないでください。ポートを占有している隣接ワークスペースは、これら3つすべてを満たします。

ポートの所有者が隣接ワークスペースのプロセスである場合（ポートの占有）：

1. 現時点で、どのワークスペースが固定ポートを所有すべきかを決めます。通常は、issue に記載されたワークスペースです。
2. 現在の所有者のワークスペースと、そのプロセスを存続させているライブエージェント実行または管理対象ランタイムサービスがあるかを確認します。実際の /proc/<pid>/cwd、隣接ワークスペースの実行ワークスペース記録、所有する issue／実行の状態を使用してください。対象のランタイム行から所有者を推測しないでください。
3. 所有者を先に、その所有者自身の管理された制御経路を通じて停止します。隣接ワークスペースのランタイムサービスを停止するか、それを監視して再起動しているライブ実行を停止／キャンセルしてください。監視プロセスが動作中のまま、隣接ワークスペースのプロセスを直接終了しないでください。プロセスがすぐに再起動してポートを取り戻します。
4. 安定するまで待ち、ポートが未バインドのままであることを確認します。すぐに再バインドされる場合は、対象をループで再起動するのではなく、まだ動作中の監視プロセスを特定して停止してください。
5. 競合する所有者を停止してから、対象のサービスを起動または再起動し、識別を再確認します。

curl -sS -X POST \
  "$PAPERCLIP_API_URL/api/execution-workspaces/$EXECUTION_WORKSPACE_ID/runtime-services/restart" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
  -H "Content-Type: application/json" \
  --data-binary '{"workspaceCommandId":"service:paperclip-dev"}'

6. 競合する所有者が停止状態を保っている場合にのみ、再起動が有効です。ポートが再び占有された場合は、所有者／監視プロセスを再度停止して原因を調べてください。対象を再起動して対抗することを繰り返さないでください。
7. 2つのワークスペースを本当に同時に実行する必要がある場合、固定ポートを共有することはできません。不要な方を停止し（そのワークスペース自身の管理された停止操作を行うか、再起動させている実行を終了します）、どのワークスペースがポートを所有することになったかを issue コメントに記載してください。また、再起動を繰り返すのではなく、固定ポートの競合を製品の問題としてエスカレーションしてください。

成功と判断する前に、競合が疑われる隣接ワークスペースも取得し、それらの runtimeServices[].port の値を比較してください。複数のワークスペースに、対象のポートを要求する running の行がある場合は、常に解決すべき競合であり、回避して済ませる状態ではありません。

データベースの完全な再シード

アプリにセットアップが未完了と表示される場合、ログインはできてもデータがない場合、クローンしたアプリに想定される会社／issue／エージェントが存在しない場合、またはユーザーが通常の分離されたワークスペース用データベースを明示的に求めている場合は、完全な再シードを使用してください。

npx paperclipai worktree reseed --from-instance default --seed-mode full --yes

再シード後は、管理されたランタイム経路を通じて再起動してください。再シードによって、ID がローカルのプロセスレジストリと一致しなくなったランタイムサービス行がコピーされることがあるため、起動後にランタイムの引き継ぎと照合を確認する必要があります。

提供中のアプリで認証とデータが正しく登録された製品データの両方を確認できるまで、再シードが完了したと判断しないでください。ユーザー／アカウント行を一時的に挿入しただけの場合、それは診断の手がかりであり、最終状態ではありません。

コア検証プローブ

SERVICE_URL に、ランタイム API から返されたサービス URL を設定します。

curl -sS "$SERVICE_URL/api/health" | jq
curl -sS -I "$SERVICE_URL/" | head

期待されるヘルス状態：

• status: "ok"
• bootstrapStatus: "ready"
• bootstrapInviteActive: false

拒否すべき状態：

• bootstrap_pending：インスタンスに初回管理者のセットアップ画面が表示されます
• database_unreachable：Web プロセスはリッスンしていますが、データベースが停止しています
• ルートが 200 を返す一方で /api/health が異常：古いプロセスを誤って引き継いだ不具合、または稼働中の Node プロセスの背後にある組み込みデータベースの停止

プロセスがすでにリッスンしている場合は、ポートの所有者を確認します。

lsof -nP -iTCP:"$SERVICE_PORT" -sTCP:LISTEN || true

管理された停止に失敗した後、古い Paperclip 開発ランナープロセスを特定して削除する目的に限って使用してください。無関係なプロセスは強制終了しないでください。

メインのコントロールプレーンのランタイム状態を検証する

メイン API から実行ワークスペースを読み取り、ランタイムサービスレコードを調べます。

curl -sS \
  "$PAPERCLIP_API_URL/api/execution-workspaces/$EXECUTION_WORKSPACE_ID" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq

対象サービスには、次の状態が表示されるはずです。

• 一致するワークスペースのコマンド ID。通常は service:paperclip-dev
• status: "running"
• 存在する場合は、正常なヘルスフィールド
• 確認対象のものと同じ URL
• 稼働中のポート所有者に対応するローカルプロバイダーの参照

メインアプリで running と表示されていても /api/health が異常な場合は停止し、管理されたランタイムを通じて古いプロセスを置き換えます。

提供されているワークスペースのランタイム状態を検証する

クローンされた Paperclip アプリでも、このサービスを認識できる必要があります。エージェント認証を利用できる場合は、提供されているアプリを通じて同じ実行ワークスペースを照会します。

curl -sS \
  "$SERVICE_URL/api/execution-workspaces/$EXECUTION_WORKSPACE_ID" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq

提供されているアプリでも、サービスが同じ URL で running／healthy であると認識される必要があります。再シード後にメインのコントロールプレーンと提供されているアプリの状態が一致しない場合、クローンされたデータベースに、ローカルのプロセスレジストリと一致しないランタイムサービス ID がコピーされている可能性があります。通常の起動／引き継ぎ手順をもう一度実行し、両方を検証してください。この領域のコードを変更した場合は、対象を絞った回帰テストを追加してください。

認証とデータが読み込まれていることを検証する

認証とデータの確認には、生の DB クエリではなく、プロダクト API とブラウザー／QA によるレビューを使用してください。

最低限の API チェック：

curl -sS "$SERVICE_URL/api/health" | jq '.status, .bootstrapStatus'
curl -sS "$SERVICE_URL/api/companies" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq
curl -sS "$SERVICE_URL/api/agents/me" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" | jq

その後、プライマリインスタンスに存在するはずの既知のプロジェクト、課題キー、会社、実行ワークスペースなど、クローンされたプロダクトレコードを少なくとも 1 件、API を通じて検証します。無作為に選んだテーブルのレコード数ではなく、現在の課題に関連するレコードを選んでください。

ブラウザーまたは QA による確認：

• サービス URL を開く
• 初回管理者のセットアップ画面が表示されなくなっていることを確認する
• 通常の開発用認証情報でサインインする
• ボードに会社／プロジェクト／課題／実行が読み込まれていることを確認する
• ワークスペースサービスに、稼働中の URL が表示されていることを確認する

この環境でブラウザーを起動できない場合は、QA に視覚的な確認とログイン確認を依頼し、実行可能な API チェックはすべて完了してください。ブラウザーによる検証を委任したことと、その理由を報告してください。

よくある障害と対処法

サービス URL が別のワークスペースを提供している（ポートの占有）

症状：ワークスペース URL を開くと、正常に動作する Paperclip アプリが表示されますが、それは別のワークツリーにあるアプリです。ブランチやデータが異なる、または UI を操作すると別のワークスペースのページに移動してしまいます。

考えられる原因：固定されたサービスのポートが別のワークスペースのプロセスに占有されており、起動時の引き継ぎによって、そのプロセスがこのワークスペースのランタイム行に関連付けられています。別のワークスペースのアプリは実際に正常なため、ヘルスチェックは成功します。

対処法：「Port conflicts and workspace identity」の所有者優先の手順に従い、別のワークスペースのサービスまたはそれを監督する実行を特定して停止し、ポートが空いたままであることを確認してから、対象サービスを起動または再起動します。新しいポート所有者の /proc/<pid>/cwd が対象のワークツリー内を指していることを再検証します。

検証：ID の確認に成功し、URL を通じて提供されるワークスペース固有のレコード（ブランチ、課題キー、またはワークスペース ID）が対象ワークスペースと一致していること。

非管理された起動後に記録されたポートの不一致

症状：ランタイムのレコードと実際のリスナーでポートが一致しない、または手動でアプリを起動した後に、以前固定されていたポートが変わっています。

考えられる原因：管理対象外の pnpm dev（たとえば --bind lan を指定した場合）では、管理対象の固定ポートではなく、独自のポートが選択されます。

対処方法：管理対象外のプロセスを停止してから、管理対象の方法で起動します。記録された URL のポートとバインドされたポートが一致し、ID チェックに合格することを確認します。

セットアップゲートが表示される

症状：ページに、このインスタンスの管理者がまだ設定されていないと表示されます。

対処方法：プライマリインスタンスからワークツリーを完全に再シードし、管理対象のサービスを再起動します。最初の管理者を設定するとゲートが解除される場合がありますが、ユーザーが通常の分離されたワークスペースデータベースを求めている場合は、完全な再シードが正しい対処方法です。

確認方法：/api/health の bootstrapStatus: ready を確認し、ログインできることと、データが登録されていることを確認します。

ログインできない

症状：ブートストラップは完了していますが、ユーザーの通常の開発用認証情報ではログインできません。

考えられる原因：分離された DB にロールまたはブートストラップ状態はありますが、プライマリインスタンスの認証ユーザーやアカウントがありません。

対処方法：完全に再シードします。最後の対処として Better Auth のユーザー／アカウントの行だけを手動でコピーしないでください。

確認方法：ブラウザー／QA からのユーザーログインと、エージェントキーを使った /api/agents/me を確認します。

ログインできるがデータがない

症状：ユーザーはサインインできますが、企業／課題／プロジェクト／実行が空、または明らかに不完全です。

考えられる原因：データベース全体を複製せず、部分的な認証修復を行いました。

対処方法：完全に再シードし、管理対象の方法で再起動してから、複製された代表的なレコードを確認します。

ポートはリッスンしているが、ヘルスチェックでデータベースに到達できないと表示される

症状：curl -I / は応答を返しますが、/api/health では database_unreachable が報告されます。

考えられる原因：組み込み Postgres の停止後も、古い Node／Web プロセスが残っています。

対処方法：まず管理対象の方法で停止します。プロセスが残る場合は、対象ポートに対応する Paperclip dev-runner のプロセスグループを特定し、そのグループだけを終了します。その後、管理対象の方法で起動します。

確認方法：安定するまで待った後に /api/health が正常であり、ランタイムのレコードも正常であることを確認します。

メインのコントロールプレーンが実行中のサービスを把握できなくなる

症状：サービス URL は動作しますが、メインアプリではサービスが作成されていない、または停止していると表示されます。

考えられる原因：切り離された回避策用プロセス、古いプロバイダー参照、またはヘルスチェックではなくルート URL を信頼したサービスの引き継ぎです。

対処方法：管理対象外のプロセスを終了し、管理対象ランタイムを通じて再起動します。コードの修正が必要な場合は、引き継ぎ時に /api/health を確認し、正常でない引き継ぎ済みプロセスを置き換え、現在のプロバイダー参照を記録するようにします。

確認方法：メインのランタイム行と /api/health の内容が一致することを確認します。

完全な再シード後、提供中のアプリがサービスを把握できなくなる

症状：メインアプリでは paperclip-dev が実行中と表示されますが、複製されたアプリにコピーされた runtime-service 行の ID が、ローカルレジストリの ID と一致しません。

考えられる原因：通常の DB クローンにより、プライマリインスタンスの永続化済みランタイム行が、異なるローカルプロセスメタデータを持つ分離環境にコピーされました。

対処方法：管理対象の方法で再度起動または引き継ぎを行います。コードの修正が必要な場合は、引き継ぎ時にコピーされた行 ID だけでなく、サービス ID とポートを使って整合性を取るようにします。

確認方法：メインアプリと提供中のアプリの両方で、同じサービスが running／healthy と表示されることを確認します。

複製されたアプリでランタイムの起動時に権限エラーまたは実行 FK エラーが返される

症状：提供中のアプリから起動すると 403 が返される、またはアクティビティのログ記録に失敗する前に変更が一部適用されます。

考えられる原因：複製された課題／実行／エージェントの状態が現在のハートビートと一致しない、または再シード後に複製されたデータベースに実行 ID がありません。

対処方法：メインのコントロールプレーンで管理されるランタイムの経路と完全な再シードを優先します。複製されたアプリの状態自体を修復する必要がある場合は、まず通常の Paperclip の課題／実行の遷移を使います。生の DB 編集でこの状態を隠さないでください。通常の経路を妨げる場合は、該当するガードまたは欠落している行を正確に報告します。

過去の修復で繰り返し発生した落とし穴

これらは過去の修復で問題になったことがあるため、詳細なデバッグを始める前に確認してください。

• ワークツリーインスタンスのログは ~/.paperclip-worktrees/instances/<slug>/logs にあります。ログインや起動の失敗について推測する前に、ログを確認してください。
• LAN または tailscale の IP 経由でサービスを調べると 403 が返る一方、127.0.0.1（または paperclip-dev ホスト名）では動作することがあります。認証に問題があると結論づける前に、まずループバックを調べてください。
• ブラウザー QA で空の会社パス（例：/FOR/...）が表示された場合、再シードに失敗したと結論づける前に、クローンしたデータに存在する会社キー（例：/PAP/...）に切り替えてください。
• ランタイムまたは課題の変更で 409 が発生する場合、通常は別の実行中の処理が所有権ロックを保持しています。強制せず、待つか、課題を通じて調整してください。
• 完全に再シードした後、クローンした DB にローカルプロセスと一致しないコピー済みの runtime-service 行が含まれていることがあります。コピー済みの行をそのまま信用せず、管理対象の起動と ID チェックを再実行してください。

コード変更が必要な場合

通常の運用上の修復で製品のバグが明らかになった場合に限り、コードを変更してください。この種の障害の例：

• ローカルのポート所有者の検出で、誤った lsof 引数が使われていた
• サービスの引き継ぎで /api/health ではなくルートの 200 を信頼していた
• ポート所有者の引き継ぎで、所有者の実際の /proc/<pid>/cwd を検証せず、要求された cwd を記録していたため、兄弟ワークスペースのプロセスが引き継がれていた
• 固定されたサービスのポートが兄弟ワークスペース間で衝突していた
• 異常な引き継ぎ済みサービスが終了または置き換えられていなかった
• 再シードされた runtime-service ID がローカルのプロセスレジストリと照合されていなかった

影響を受けるサービスのテストファイルに、対象を絞ったテストを追加してください。ワークスペースのランタイム修復では、通常、次のように範囲を絞って検証します：

pnpm exec vitest run server/src/__tests__/workspace-runtime.test.ts
git diff --check

論理的にまとまったコード変更をコミットし、そのコミットへのリンクを課題のコメントに記載してください。追跡対象のコードに変更がなかった場合は、そのことを明記してください。

最終的な課題コメントのテンプレート

「動作します」のような曖昧な表現ではなく、具体的な証拠を記載してください。

Fixed and verified the workspace service.

Root cause:
- <why it broke>

Fix:
- <normal reseed/start/repair steps>
- <code commit if any>

Verified:
- main control plane shows <service> running/healthy at <url>
- served workspace app shows the same service running/healthy
- port owner identity: /proc/<pid>/cwd resolves inside the target worktree
- <url>/api/health is ok with bootstrapStatus ready
- root page returns 200 and no setup gate
- dev login verified by <agent browser / QA / user> without posting credentials
- cloned data verified via <specific API records>
- targeted tests: <commands>

Remaining:
- <none, or named owner/action if blocked>

すべての成功条件を満たした場合に限り、課題を done にしてください。満たしていない場合は、担当する解除責任者と必要な具体的なアクションを明記して、blocked にしてください。