Superset/Codex 連携

このページは Superset workspace 連携と Codex App worktree 連携の runbook です。MCP/CDP、Superset mode/route、Codex sync/unlink/cleanup、手動検証を扱います。

Codex SessionStart hook の設定手順は Codex hook 連携 に置きます。このページでは hook に入れる前後の確認と、Superset 側の record / route の見方に絞ります。

このページの範囲

このページで扱うもの:

• swt issue / swt pr が Superset workspace を作成・登録する経路
• --superset-mode と --superset-transport の選び方
• MCP、CDP、v2 host DB、legacy v1 local.db の役割
• swt codex sync-*、unlink-workspace、prune-links、cleanup-archived-workspaces の使い分け
• Superset/Codex 連携の手動検証とトラブルシューティング

このページで扱わないもの:

• gwt の基本操作は gwt の使い方 を参照
• GitHub Issue/PR から worktree を作る日常 workflow は swt workflow を参照
• Codex hook の JSON 設定、trust/enable 診断、check-hooks の詳細は Codex hook 連携 を参照

README 代表導線

まず選ぶべき経路

legacy v1 state を明示的に確認したい場合だけ --superset-mode=legacy-v1 を付けます。default v2 mode は v1 local.db へフォールバックしません。

Superset mode と route

--superset-mode は参照・更新する Superset state の version、--superset-transport はその state に到達する経路です。

workspace 作成系の出力では superset-route=<mode>/<transport> が出ます。record 直接操作では superset-mode=<mode> と superset-route=v2/db または superset-route=legacy-v1/db が出ます。

Transport precedence

transport の優先順位は command の責務によって異なります。swt issue / swt pr は Superset workspace を作成する command、swt codex sync-* は既存の Codex App 管理 worktree を Superset record と sidebar state に採用する command です。

swt codex sync-* --superset-transport=mcp は「MCP existing worktree adoption capability がある場合だけ MCP で採用する」という指定です。現行 Superset v2 でその capability が検出されない場合は、警告を出して host-service adopt、必要に応じて CDP importer へ fallback します。host-service と CDP がどちらも利用できない場合は error になります。将来 Superset MCP Server に既存 worktree adoption tool が追加された場合も、利用可能として扱うのは probe で検出した場合だけです。存在しない MCP tool を利用可能な前提として docs や運用を組まないでください。

MCP Server 経由の workspace 作成

Superset 1.8.5/v2 では MCP Server 経由を推奨します。CDP と異なり renderer 内部の tRPC shape に依存しないため、Superset Desktop の内部実装変更の影響を受けにくい経路です。

export SUPERSET_MCP_API_KEY="your-api-key"

# デバイスIDは通常自動検出される。必要な場合だけ明示する
# export SUPERSET_DEVICE_ID="a25e1918-85c1-4be2-8418-6220e447ad51"

# endpoint を明示したい場合だけ指定する
# export SUPERSET_MCP_ENDPOINT="https://api.superset.sh/api/v2/agent/mcp"

swt issue 123
swt pr 456

SUPERSET_MCP_ENDPOINT を指定しない場合、--superset-mode=v2 は https://api.superset.sh/api/v2/agent/mcp、--superset-mode=legacy-v1 は https://api.superset.sh/api/agent/mcp を使います。SUPERSET_MCP_ENDPOINT を明示した場合は mode に関わらずその URL が優先されるため、mode 別の default endpoint を確認するときは先に unset してください。

unset SUPERSET_MCP_ENDPOINT
swt issue 125 --superset-mode=legacy-v1

MCP 経由では applyPrefix を制御できないため、Superset のブランチプレフィックス設定に従ったブランチ名が作成されます。CDP 経路を明示する場合は --superset-transport=cdp、legacy v1 state で CDP を使う場合は --superset-mode=legacy-v1 --superset-transport=cdp を指定します。

v2 MCP で workspace 作成が成功した後も、Superset の sidebar local state 補完は CDP availability に依存します。Superset 1.4.1 以降は production ビルドで CDP remote debugging が無効化されているため、作成済み workspace が sidebar に出ない場合は、Superset を open -a Superset --args --remote-debugging-port=0 --remote-allow-origins='*' で起動し、superset-route=v2/mcp の sidebar 補完 warning を確認してください。workspace record と実体 worktree の作成成功は、sidebar 補完失敗とは別扱いです。

swt codex unlink-workspace は MCP v2 の workspaces_delete を使いません。workspaces_delete は workspace 実体の削除を伴う destructive な操作であり、record-only unlink ではありません。

CDP fallback

CDP は Superset Desktop の renderer と通信する fallback 経路です。--superset-transport=cdp で v2 CDP、--superset-mode=legacy-v1 --superset-transport=cdp で legacy v1 CDP を明示できます。

Superset 1.4.1 以降は production ビルドで CDP が無効化されているため、CDP fallback を検証する場合は次のように起動します。

open -a Superset --args --remote-debugging-port=0 --remote-allow-origins='*'

swt pr は既存 PR branch を fetch して worktree を作るため、新規 branch を作る swt issue と fallback の見方が少し異なります。Superset 1.9.x の v2 PR workspace では renderer の legacy workspaces.create / openExternalWorktree に raw project ID を渡すと Project ... not found になり得るため、swt pr --superset-transport=cdp はローカル worktree 作成後に v2 host-service adopt で host DB record を登録し、CDP は sidebar state の補完に使います。

swt pr 456 --superset-transport=cdp
# 期待する出力: Superset workspace created: ... (superset-route=v2/cdp)

CDP が使えない状態でも git worktree 自体はローカルに作成されます。workspace 登録に失敗した場合は stderr の superset-route と warning を確認し、Superset を CDP 有効で起動してから再実行します。

Superset host DB と legacy v1 local DB

SUPERSET_HOME_DIR 未指定時は ~/.superset を Superset state root として参照します。

v2 host DB は projects.repo_path / workspaces.worktree_path schema を持つ host DB を host ID の辞書順で探索します。host directory の読み取り失敗、manifest / host DB の stat 失敗、schema 確認失敗などの実エラーは、v1 fallback で隠さずエラーにします。

登録済み判定では repo 名や branch 名から path を予測しません。DB に保存された workspaces.worktree_path または worktrees.path を canonical path 比較に使います。

v1 local.db に誤登録された疑いがある場合は、対象 Codex worktree path を指定して legacy mode の削除予定だけ確認します。

swt codex unlink-workspace /path/to/codex-worktree --superset-mode=legacy-v1 --dry-run
swt codex unlink-workspace /path/to/codex-worktree --superset-mode=legacy-v1

# v2 側に二重登録がないか確認する
swt codex unlink-workspace /path/to/codex-worktree --superset-mode=v2 --dry-run

通常の swt issue / swt pr worktree は Codex metadata を持たないため、swt codex unlink-workspace の対象外です。通常 worktree を作り直す場合は、先に既存 worktree とローカルブランチを gwt remove --delete-branch /path/to/worktree などで削除して、branch / path の衝突を避けます。

Codex worktree を Superset に同期する

swt codex sync-current-workspace は Codex App 管理 worktree を検出し、未登録の場合だけ実体 path を Superset workspace として登録します。Codex App が作成した実体 worktree は $CODEX_HOME/worktrees/<id>/<repo> に残し、Superset にはその実体 path を登録します。active thread がすべて source=exec の review/adversarial-review、または thread_source=subagent / source={"subagent":...} 由来で has_user_event=false の場合は、Codex UI に出ない内部実行の workspace とみなして同期対象外にします。

# cwd を対象に同期
swt codex sync-current-workspace

# 対象 path を明示
swt codex sync-current-workspace --path "$PWD"

# hook 向けに stdout を抑制
swt codex sync-current-workspace --quiet

hook に入れる前に、通常はカレントリポジトリの Codex worktree だけを dry-run で確認します。

swt codex sync-workspaces --dry-run
swt codex sync-workspaces --repo git-worktree --dry-run
swt codex sync-workspaces --all --dry-run

sync-workspaces は default ではカレントディレクトリからリポジトリ名を解決し、そのリポジトリの Codex worktree だけを同期します。git リポジトリ外から実行する場合は --repo <name> または --all が必要です。

swt codex sync-* の default route は v2/host-service です。v2 project が見つからない場合は v1 local.db にフォールバックせず、明示エラーになります。legacy v1 へ登録したい場合だけ --superset-mode=legacy-v1 を指定します。

CDP port が無い状態で sync した場合も、host-service の workspace record 登録と sidebar 補完は別扱いです。registration=ok; ui-reflection=skipped が出ても record は登録済みとして残り、UI 反映失敗を registration failure として扱いません。ただし復旧手順は warning の classification で分かれます。classification=cdp-unavailable; retry=next-sync は CDP port が一時的に未準備な状態で、Superset を CDP 有効で起動した後の次回 sync で sidebar 補完を再試行できます。classification=cdp-disabled-superset-running; retry=after-cdp-relaunch; action=quit-and-open-with-remote-debugging は Superset UI が CDP 無効で起動中のため、next-sync だけでは回復しません。

Superset update 後の世代差と CDP 再起動

Superset update 後は terminal session / host-service / terminal-host / pty-daemon が旧 Superset 世代のまま残り、UI renderer だけが新 Superset 世代で起動することがあります。これは long-lived session の仕様として扱い、swt から強制終了しません。CDP が利用可能なら UI/CDP 側の状態を別途確認できますが、CDP 無効時は host-service manifest の spawnedByAppVersion だけを diagnostic として出します。

次のような warning は、record 登録は成功しているが updater が CDP 無効で UI を再起動した状態を示します。

registration=ok; ui-reflection=skipped; classification=cdp-disabled-superset-running; retry=after-cdp-relaunch; action=quit-and-open-with-remote-debugging; diagnostic=host-service-manifest-version; host-service-version=1.9.1

この場合は次回 sync だけでは sidebar 補完が走らないため、Superset を Cmd+Q で終了し、CDP 有効で起動し直してから sync を再実行します。

open -a Superset --args --remote-debugging-port=0 --remote-allow-origins='*'

# 全 Codex worktree を再同期する場合
swt codex sync-workspaces --all

# 対象 repo だけを再同期する場合
swt codex sync-workspaces --repo git-worktree

classification=cdp-unavailable; retry=next-sync は、Superset の起動途中などで CDP port が一時的に見えない状態です。Superset を CDP 有効で起動している前提なら、同じ sync を再実行するか、hook の次回 SessionStart で再試行できます。sidebar DOM の再描画そのものは #296 の範囲で扱い、この flow では UI 反映失敗を registration failure として扱いません。

関連 Issue との責務境界

• #163 は swt issue / swt pr の workspace 作成を MCP Server へ寄せるための capability 追跡です。applyPrefix、既存 branch adoption、PR 由来 workspace 作成など、MCP 側にまだ無い作成 API を利用可能とみなさないでください。
• #296 は swt codex sync-* 後に登録済み workspace が開いている Superset sidebar DOM へ反映されない問題です。host-service record 登録や MCP 移行ではなく、renderer local state / DOM 再描画の責務として扱います。
• #306 / #307 / #308 / #309 / #310 は Superset update 後の host-service 世代差、CDP 無効起動、warning / retry guidance、runbook を扱います。CDP が生きているのに sidebar DOM へ反映されない場合は #296 の範囲です。
• このページの範囲は transport の選び方、fallback、warning の読み方です。MCP tool の追加や sidebar runtime の根本修正は、それぞれの Issue 側で扱います。

Codex hook の設定例、trust/enable 診断、swt codex check-hooks の読み方は Codex hook 連携 を参照してください。

Superset record 起点で古い workspace を監査する

swt codex stale-workspaces は Superset v2 host DB の workspace record を起点に分類します。--apply を付けない限り read-only です。Codex state DB の threads.cwd からは拾えない thread 0 件の worktree や、.superset/worktrees/... 配下の Superset 管理 worktree も監査対象に入ります。

# cwd の repo root に対応する Superset project を監査
swt codex stale-workspaces

# git リポジトリ外から repo root を明示
swt codex stale-workspaces --repo-root /path/to/repo

# repo 名で一意に解決できる project だけ監査
swt codex stale-workspaces --repo git-worktree

# 全 project を明示的に監査
swt codex stale-workspaces --all

各 record では worktree path の存在、git worktree list --porcelain 上の登録、dirty/current cwd、Codex thread 数、branch に対応する PR state を表示します。classification には codex-worktree-record、codex-missing-path-record、superset-managed-worktree、legacy-v1/local-db-record など、record の所有境界を出します。summary の superset_only は Codex thread 数の取得に成功し、threads: ... total=0 だった record 数です。.superset/worktrees/... 配下の Superset-managed worktree は swt codex の実体 cleanup 対象にせず、必要な場合は swt clean へ誘導します。open / unknown / ambiguous PR state、dirty/current cwd、git worktree 未登録は skip reason として扱います。ただし codex-missing-path-record で path 不在、git 未登録、Codex thread 0 件、Superset record が一意、project/workspace ID が有効な record は、PR state に依存しない record-only cleanup candidate として扱います。active thread が残る record は thread ID、cwd、archived state、updated_at、source、thread_source、has_user_event、title 候補、classification confidence を diagnostic として出します。active thread がすべて source=exec の review/adversarial-review、または thread_source=subagent / source={"subagent":...} 由来で has_user_event=false の場合は、Codex UI hidden thread だけの record-only cleanup candidate として扱います。分類不能な active thread や thread_source=user の thread は unknown-active-thread として削除対象外に残します。PR state は gh pr list --head <branch> --state all 相当で解決し、branch 名中の番号らしき文字列は判定に使いません。取得失敗など apply 判定に使えない情報は diagnostic として表示します。

v2 mode では CDP が利用可能な場合だけ renderer localStorage の v2-workspace-local-state-<organizationId> も read-only で読み、project scope に合う sidebar entry を host DB record の workspaceId と照合します。DB record と照合できる entry は record-backed-workspace、照合できない entry は sidebar-only-workspace として表示し、summary の sidebar_only に集計します。superset_only は host DB record 起点の件数のままなので、stale-workspaces --repo agent-dotfiles が superset_only=0 でも Superset UI に残骸が見える場合は sidebar_only と sidebar_local_state セクションを確認してください。CDP が無効な場合は record audit は継続し、sidebar_local_state: skipped classification=cdp-disabled-superset-running のように sidebar-only audit だけが skipped として表示されます。

sidebar-only-workspace は host DB record がないため、stale-workspaces --apply 単体では削除しません。常駐 cleanup などで明示的に片付ける場合は v2 mode で --cleanup-sidebar-only を追加します。手動で 1 件だけ確認したい場合は、表示された workspace ID と project context を確認し、対象 project の Codex worktree で swt codex unlink-workspace --workspace-id <workspace-id> を dry-run から試してください。

closed/merged PR の threadless stale worktree、実体 path が既に消えた record-only cleanup candidate、または Codex UI hidden thread だけの record-only cleanup candidate を cleanup する場合だけ --apply を明示します。実体 worktree 削除の対象は current cwd ではない、dirty ではない、active thread が 0 件、branch に対応する PR が head branch から一意に closed/merged と解決できる、Superset record が一意、Git worktree 登録が一意、という safety gate をすべて満たす record だけです。codex-missing-path-record の record-only cleanup は実体削除を試さず、path 不在、git 未登録、Codex thread 0 件、Superset record が一意、project/workspace ID が有効な record だけを対象にします。この場合、path missing 由来の diagnostic と open / unknown / ambiguous PR state は削除阻止理由にしません。Codex UI hidden thread だけの record-only cleanup は実体 worktree が残っていても Superset record と sidebar state だけを削除し、dirty/ignored local file や open / unknown / ambiguous PR state は削除阻止理由にしません。

swt codex stale-workspaces --apply
swt codex stale-workspaces --all --apply --cleanup-sidebar-only

--apply は通常 candidate では Superset worktree record と v2 sidebar state を先に cleanup し、その後で git worktree remove 相当により実体 worktree を削除します。record-only cleanup candidate では Superset worktree record と該当 workspace ID の v2 sidebar state だけを cleanup し、git worktree remove は呼びません。v2 sidebar state cleanup は CDP availability に依存する best-effort で、失敗時は警告を出して record cleanup と実体 worktree 削除または record-only cleanup を継続します。git worktree remove が失敗した場合は、Superset record cleanup が完了済みであることを出力します。ローカルブランチは削除しません。

Codex workspace の record を外す

swt codex unlink-workspace は Codex App 管理下の実体 worktree を残したまま、Superset workspace record だけを削除します。引数を省略すると現在の worktree を対象にします。

# 現在の worktree を対象
swt codex unlink-workspace --dry-run
swt codex unlink-workspace

# 実体 path を指定
swt codex unlink-workspace /path/to/codex-worktree --dry-run
swt codex unlink-workspace /path/to/codex-worktree

# 旧 alias の link name または symlink path を指定
swt codex unlink-workspace git-worktree-2d5a
swt codex unlink-workspace ~/.superset/worktrees/codex/git-worktree-2d5a

default の --superset-mode=v2 では v2 host DB record だけを対象にし、record 削除後に v2 sidebar local state からも同じ workspace ID を削除します。legacy-v1 record は --superset-mode=legacy-v1 を明示した場合だけ削除します。Superset workspace record の削除 API が未対応の場合は警告を出し、record を残します。

DB record 削除後に Superset sidebar だけが残った場合は、削除時に出力された workspace ID を --workspace-id に渡して sidebar state だけを再削除できます。この復旧経路は Superset renderer の local state を更新するため、Superset を CDP 有効で起動しておく必要があります。

swt codex unlink-workspace /path/to/codex-worktree --workspace-id <workspace-id>

Codex App が先に実体 directory を削除し、Superset UI だけに workspace が残った場合は、消えた $CODEX_HOME/worktrees/<id>/<repo> path を unlink-workspace に渡すと record を照合して削除できます。default は v2 host DB、--superset-mode=legacy-v1 を付けた場合は legacy local.db だけを対象にします。repo 名だけで Superset project を一意に決められない場合は --repo-root <path> で対象 project を明示します。

swt codex unlink-workspace ~/.codex/worktrees/831f/git-worktree --repo-root /path/to/repo

swt codex prune-links は過去バージョンが作成した stale な symlink alias だけを削除し、Superset workspace record には触れません。

swt codex prune-links --dry-run
swt codex prune-links

Workspace が残る理由を診断する

Codex でチャットを archive しても、archive 操作だけでは Superset workspace record は削除されません。1 件だけ理由を確認する場合は diagnose-workspace を使います。

swt codex diagnose-workspace
swt codex diagnose-workspace /path/to/codex-worktree

この command は read-only です。対象 path に対応する Superset host DB record、Codex thread、git worktree 登録、dirty/current cwd、PR state、v2 sidebar local state を照合します。active thread が残る、current cwd と一致する、PR state が open/unknown、host DB record がなく sidebar-only の可能性がある、などの理由を 1 workspace に絞って確認できます。

Archived worktree をクリーンアップする

swt codex cleanup-archived-workspaces は Codex state DB、git worktree、Superset workspace record を照合し、archived thread だけが紐づく Codex App 管理 worktree の cleanup 候補を表示します。引数なしでは dry-run として動作し、filesystem と Superset は変更しません。

swt codex cleanup-archived-workspaces

出力の主な分類:

active thread が 1 件でも残る worktree は、merged/closed PR に見えても初期 MVP では --apply の実体削除対象にしません。自動削除へ進める場合は、active thread の分類根拠、復旧手順、誤削除時の rollback を別 Issue で設計してから扱います。

候補を削除する場合だけ --apply を付けます。--apply は削除直前に同じ候補を再判定し、Superset workspace record を先に削除してから、実体 worktree を削除します。v2 mode では workspace record 削除後に v2 sidebar state も削除し、legacy-v1 mode では legacy local.db record だけを削除します。

swt codex cleanup-archived-workspaces --apply

ローカルブランチは default では残します。実体 worktree 削除後にローカルブランチも削除する場合だけ、--delete-branch を明示します。

swt codex cleanup-archived-workspaces --apply --delete-branch

cleanup-archived-workspaces は cleanup 実行中の global lock を取りません。dry-run 後に別プロセスが同じ path を使い始めた場合は、--apply の直前再判定で対象外になり得ます。

手動検証チェックリスト

Superset/Codex 連携を手動確認する場合は、実際の Issue / PR 番号を使い、同じ番号を繰り返し使って branch / path が衝突しないようにします。

# v2 host state の存在を確認
ls "${SUPERSET_HOME_DIR:-$HOME/.superset}/host"

# Superset CLI がある環境では CLI が起動できることだけ確認
superset --help

# MCP API key を設定して Issue / PR の作成経路を確認
export SUPERSET_MCP_API_KEY="your-api-key"
unset SUPERSET_MCP_ENDPOINT
swt issue 123
# 期待する出力: superset-route=v2/mcp
swt pr 456
# 期待する出力: superset-route=v2/mcp

# MCP 未設定時の fallback を確認
unset SUPERSET_MCP_API_KEY
open -a Superset --args --remote-debugging-port=0 --remote-allow-origins='*'
swt issue 124
# CDP 有効時の期待する出力: superset-route=v2/cdp

# Codex App worktree の同期予定を確認
swt codex sync-workspaces --dry-run
# 期待する出力: superset-route=v2/host-service

# registered workspace の record unlink が実体 worktree を消さないことを確認
swt codex unlink-workspace /path/to/codex-worktree --dry-run
# 期待する出力: superset-mode=v2 superset-route=v2/db

# archived cleanup は必ず dry-run から確認
swt codex cleanup-archived-workspaces
# 期待する出力: Codex archived worktree cleanup candidates (dry-run)
swt codex cleanup-archived-workspaces --apply
# 期待する出力: summary (apply): deleted=... record_only=... skipped=... failed=0

# legacy v1 は明示した場合だけ使う
export SUPERSET_MCP_API_KEY="your-api-key"
unset SUPERSET_MCP_ENDPOINT
swt issue 125 --superset-mode=legacy-v1
# 期待する出力: superset-route=legacy-v1/mcp
swt issue 126 --superset-mode=legacy-v1 --superset-transport=cdp
# 期待する出力: superset-route=legacy-v1/cdp

swt codex unlink-workspace <worktree-path-or-alias> --dry-run では Superset workspace record の削除予定だけを確認し、Codex App 管理下の $CODEX_HOME/worktrees/<id>/<repo> が削除対象に含まれないことを確認してください。

トラブルシューティング

関連ドキュメント

• gwt の使い方
• swt workflow
• Codex hook 連携