Codex hook 連携

swt codex sync-current-workspace は、Codex App が作成した worktree を Superset workspace として扱うための同期コマンドです。Codex 管理 worktree の実体は $CODEX_HOME/worktrees/<id>/<repo> に残し、Superset へはその実体 path を登録します。

初回確認

hook に入れる前に、通常はカレントリポジトリの Codex worktree だけを対象に同期予定を確認します。

swt codex sync-workspaces --dry-run

任意のディレクトリや git リポジトリ外から特定リポジトリを確認する場合は、対象リポジトリ名を明示します。

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

全リポジトリを横断して確認したい場合だけ --all を指定します。

swt codex sync-workspaces --all --dry-run

--dry-run は filesystem と Superset を変更しません。出力に問題がなければ、必要に応じて同じ対象指定から --dry-run を外して一度だけ実同期します。git リポジトリ外から実行する場合は --repo <name> または --all が必要です。同期後も実体 worktree は Codex App 管理下に残り、Superset には実体 path が登録されます。

Superset 1.8.5/v2 環境の確認

swt issue / swt pr の workspace 作成では Superset 1.8.5/v2 の MCP Server を優先します。一方、Codex hook 連携は Codex App worktree の実体 path を Superset に登録する経路で、default では v2 host DB に直接 record を作ります。superset CLI が PATH に無い環境でも動作します。

# Superset v2 host state があるか確認
ls "${SUPERSET_HOME_DIR:-$HOME/.superset}/host"

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

# hook に入れる前に同期予定だけ確認
swt codex sync-workspaces --dry-run

swt codex sync-* の default route は v2/host-service です。v2 project が見つからない場合は v1 local.db にフォールバックせず、明示エラーになります。legacy v1 state へ登録したい場合だけ --superset-mode=legacy-v1 を指定します。default route でも v2 sidebar state の補完に CDP を使うため、実同期前に Superset を CDP 有効で起動してください。

CDP port が開いていない間に swt codex sync-workspaces --all --quiet が走った場合でも、host-service の workspace record 登録は成功扱いになります。sidebar local state の補完は登録済み record に対して再試行できますが、retry の値で次の行動が変わります。classification=cdp-unavailable; retry=next-sync は CDP port が一時的に未準備で、Superset を CDP 有効で起動した後の次回 sync で回復できます。classification=cdp-disabled-superset-running; retry=after-cdp-relaunch; action=quit-and-open-with-remote-debugging は Superset UI が CDP 無効で起動中のため、次回 sync だけでは回復しません。

警告: Superset workspace 名同期をスキップしました (… registration=ok; ui-reflection=failed; classification=name-sync|cloud-row-sync; retry=next-sync; …) は sidebar local state の追加は試みたが、追加の反映や補完を完了できなかった状態です。詳細は次の表で分類します。

watcher や SessionStart hook のログでは classification と retry を優先して読みます。

MCP Server の設定は主に swt issue / swt pr の workspace 作成で使います。現行の Codex hook 用 swt codex sync-* は MCP existing worktree adoption capability が未検出のため、SUPERSET_MCP_API_KEY を参照せず default の v2/host-service へ解決します。将来 Superset 側に既存 worktree adoption capability が追加され、実装が probe で検出した場合だけ MCP route を使います。

出力の superset-mode は参照・更新する Superset state、superset-route はその state への経路です。Codex hook 連携の default は superset-mode=v2 と superset-route=v2/host-service で、record 確認や削除の dry-run では superset-route=v2/db が出ます。legacy-v1/db が出るのは --superset-mode=legacy-v1 を明示した場合だけです。

Superset update 後の terminal session / host-service 世代差と CDP 有効起動の復旧手順は、Superset/Codex 連携 を参照してください。

swt codex unlink-workspace は record-only unlink です。MCP v2 の workspaces_delete は workspace 実体を削除する destructive な操作なので、Codex App 管理 worktree の unlink には使いません。 default の --superset-mode=v2 では v2 host DB record だけを対象にし、legacy-v1 record を外す場合は --superset-mode=legacy-v1 を明示します。 v2 では DB record 削除後に sidebar local state からも同じ workspace ID を削除します。DB record を先に消して sidebar だけ残った場合は、削除時に出力された workspace ID を使って swt codex unlink-workspace /path/to/codex-worktree --workspace-id <workspace-id> を実行すると sidebar state だけ再削除できます。 Codex App が先に実体 directory を削除し、Superset UI だけに残った workspace は swt codex unlink-workspace ~/.codex/worktrees/<id>/<repo> で v2 host DB record を照合して削除できます。repo 名から project を一意に決められない場合は、--repo-root <path> を追加してください。

# 登録済み record を外す前に、実体 worktree が削除対象に入らないことを確認
swt codex unlink-workspace /path/to/codex-worktree --dry-run

# 実体が消えた Codex workspace record の復旧
swt codex unlink-workspace ~/.codex/worktrees/831f/git-worktree --repo-root /path/to/repo

# v1 local.db へ誤登録された record の削除予定を確認
swt codex unlink-workspace /path/to/codex-worktree --superset-mode=legacy-v1 --dry-run

# v1 local.db 側の record だけを削除
swt codex unlink-workspace /path/to/codex-worktree --superset-mode=legacy-v1

Record audit

Codex thread 起点の cleanup 候補だけでなく、Superset v2 host DB の workspace record を起点に古い workspace を監査したい場合は stale-workspaces を使います。

swt codex stale-workspaces
swt codex stale-workspaces --repo-root /path/to/repo
swt codex stale-workspaces --repo git-worktree
swt codex stale-workspaces --all

1 件だけ理由を確認したい場合は diagnose-workspace を使います。Codex でチャットを archive しても Superset workspace が残る場合、この command は対象 path の host DB record、Codex thread、dirty/current cwd、PR state、v2 sidebar local state を read-only で照合し、active thread や current cwd などの skip reason を表示します。

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

--apply を付けない限り read-only です。thread が 0 件の record や Superset 管理 worktree も表示し、classification で codex-worktree-record、codex-missing-path-record、superset-managed-worktree、legacy-v1/local-db-record などを区別します。summary の superset_only で Codex thread が 0 件だった record 数、audit_only で active thread が残る record 数、superset_managed で Superset 管理 worktree 数、legacy_records で legacy local.db record 数を集計します。v2 mode かつ CDP が利用可能な場合は renderer localStorage の sidebar local state も read-only で照合し、host DB record がない entry を sidebar-only-workspace として表示して sidebar_only に集計します。superset_only=0 でも UI に workspace 残骸が見える場合は、sidebar_local_state セクションと sidebar_only を確認してください。CDP 無効時は record audit を継続し、sidebar-only audit だけを sidebar_local_state: skipped として表示します。dirty/current cwd/open PR/unknown PR state などは skip reason、active thread が残る record は thread source まで表示します。ただし codex-missing-path-record で path 不在、git 未登録、Codex thread 0 件、Superset record が一意、project/workspace ID が有効な record は、PR state に依存しない record-only cleanup candidate として扱います。active thread diagnostic には thread ID、cwd、archived state、updated_at、source、thread_source、has_user_event、title 候補、classification confidence が出ます。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 として削除対象外に残します。取得失敗など削除判定に使えない情報は diagnostic として表示します。

sidebar-only-workspace は stale-workspaces --apply 単体では削除しません。host DB record がない renderer localStorage だけの状態なので、常駐 cleanup などで明示的に片付ける場合は v2 mode で --cleanup-sidebar-only を追加します。手動で 1 件だけ確認したい場合は、表示された workspace ID を使い、対象 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 件、PR state が branch head から一意に closed/merged と解決できる、Superset record と git worktree 登録が一意、という safety gate をすべて満たす必要があります。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 は削除阻止理由にしません。通常 candidate は Superset record と v2 sidebar state を先に削除し、その後で git worktree remove 相当により実体 worktree を削除します。record-only cleanup candidate は Superset record と該当 workspace ID の v2 sidebar state だけを削除し、git worktree remove は呼びません。v2 sidebar state cleanup は CDP availability に依存する best-effort で、失敗時は警告を出して cleanup を継続します。ローカルブランチは削除しません。

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

Archived cleanup

archive 済みの Codex thread に紐づく worktree を掃除する場合は、まず dry-run で候補を確認します。

swt codex cleanup-archived-workspaces

Codex の archive 操作は Codex state DB の thread を archive 済みにするだけで、Superset workspace record の削除ではありません。SessionStart sync hook は登録・再同期の hook であり、archive cleanup は実行しないため、workspace を掃除する場合は dry-run で対象と skip reason を確認してから --apply を明示します。

この command は Codex state DB、git worktree、Superset workspace record を照合し、threads.cwd が指す Codex App 管理 worktree を分類します。candidates は archived thread だけが残る実体 worktree の削除候補、missing_record_only は実体 directory が既に消えている Superset record-only cleanup 候補、skipped は対象外です。未アーカイブ thread が残る worktree、dirty worktree、Codex 管理外 path、metadata を解決できない path は実体削除対象から外します。

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

swt codex cleanup-archived-workspaces --apply

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

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

Codex App が先に $CODEX_HOME/worktrees/<id>/<repo> の実体 directory を削除している場合は、missing-path record-only cleanup candidate として表示されます。この場合は active thread が残っていても削除する実体 worktree が存在しないため git worktree remove は呼ばず、Superset record だけを cleanup します。v2 mode では host DB record と sidebar state、legacy-v1 mode では local.db record だけを対象にします。repo 名だけで project を一意に決められない stale record は自動削除しないため、対象 project を明示して復旧します。

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

cleanup-archived-workspaces は cleanup 実行中の global lock を取りません。dry-run 後に別プロセスが同じ path を使い始めた場合は、--apply の直前再判定で対象外になり得ます。Superset record cleanup 後に git worktree remove が失敗した場合は、出力された path の dirty 状態や Git worktree 登録を直してから同じ command を再実行してください。DB record 削除後に Superset sidebar だけ残った場合は、削除時に出力された workspace ID を使って sidebar state だけ再削除します。

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

SessionStart hook

~/.codex/hooks.json に SessionStart hook を追加すると、Codex セッション開始時に現在の workspace だけを同期できます。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "swt codex sync-current-workspace --quiet"
          }
        ]
      }
    ]
  }
}

既存の SessionStart hook がある場合は、同じ hooks 配列へ command hook を追加します。--quiet は通常時の stdout を抑制するため、hook から呼んでも Codex の画面を汚しにくくなります。失敗時のエラーは stderr に出ます。非 Codex worktree でのスキップ理由を確認したい場合は、--quiet を外して実行してください。

swt が hook の PATH から見つからない環境では、絶対パスを指定します。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/go/bin/swt codex sync-current-workspace --quiet"
          }
        ]
      }
    ]
  }
}

hook 設定後は check-hooks で現在の設定を診断できます。

swt codex check-hooks

check-hooks は read-only の診断コマンドです。~/.codex/hooks.json の SessionStart に swt codex sync-current-workspace --quiet があるか、現在の PATH で swt を解決できるか、~/.codex/config.toml の [hooks.state] に該当 hook の enabled と trusted_hash があるかを確認します。Codex hook の trust/enable state は自動変更しません。不足が出た場合は Codex UI または /hooks で hook を確認し、必要なら信頼・有効化してください。

swt が PATH で見つからないと診断された場合は、上の例のように hooks.json の command を絶対 path に変更します。config.toml の読み取りや解析ができない場合は trust/enable 状態を判定できないため、Codex UI または /hooks で確認してください。

診断結果の末尾には smoke check 用のコマンドが表示されます。実同期を hook に任せる前に、必要に応じて --dry-run で現在の workspace を確認してください。

コマンドの使い分け

unlink-workspace は特定の Superset workspace 登録を外したいときに使います。引数を省略すると現在の worktree を対象にし、実体 path、実体が消えた $CODEX_HOME/worktrees/<id>/<repo> path、または旧 alias を指定できます。cleanup-archived-workspaces --apply は archived thread だけが残る Codex App 管理 worktree の実体削除を明示的に行う command です。prune-links は target が存在しなくなった旧 symlink alias の掃除だけを行い、Superset workspace record は削除しません。

所有権の分離

Codex App が作成した実体 worktree の所有者は Codex App です。通常の swt codex sync-*、unlink-workspace、prune-links はその実体を移動・削除せず、Superset workspace record だけを管理します。実体 worktree を削除するのは swt codex stale-workspaces --apply または swt codex cleanup-archived-workspaces --apply を明示した場合だけです。

$CODEX_HOME/worktrees 全体を ~/.superset/worktrees 配下へ symlink しないでください。ディレクトリ全体を共有すると、Codex App と Superset のどちらが実体を削除してよいかが曖昧になります。unlink-workspace や prune-links を実行しても実体 worktree は残ります。

Superset 側で workspace を削除する場合も、Codex App 管理下の実体 worktree は Superset 管理ディレクトリへ移動しません。swt codex sync-current-workspace --quiet は hook から繰り返し呼んでも、登録済みの canonical path を検出して二重登録を避けます。Codex UI に出ない内部 review/subagent thread だけの workspace は同期対象外にするため、record-only cleanup 後に hook で再登録されることも避けます。

swt issue / swt pr で作成した Superset 管理 worktree を Codex App で開く場合は、既存 worktree を Codex 管理ディレクトリへ移動せず、次のように開きます。

codex app <worktreePath>

この運用なら、既存の swt issue / swt pr の作成先と Codex App の一時 worktree 管理を混ぜずに済みます。