codexteer 0.18.2 → 0.19.0

package/src/help-local.mjs

@@ -0,0 +1,508 @@
+import { OPTIONS_INVALID, RUNTIME_NOT_READY, RUNTIME_UNAVAILABLE } from "./help-errors.mjs";
+const RESTART_SHARED = "ユーザーが作業を終えてDesktopを終了し、codexteer desktop startで起動し直す。codexteerは自動で起動・再起動しない。";
+
+const sharedRuntimeErrors = [
+  RUNTIME_UNAVAILABLE,
+  RUNTIME_NOT_READY,
+];
+
+const desktopReadOnlyError = {
+  code: "DESKTOP_READ_ONLY",
+  when: "--connection desktop（観測専用）で、送信・作成・撤回・修復・UI操作などを実行した",
+  action: "接続は自動で切り替わらない。必要なら既定sharedで別に実行する。監督中に--connectionを外して送信を回避しない。",
+};
+
+const supervisorForbiddenError = {
+  code: "SUPERVISOR_CONTROL_FORBIDDEN",
+  when: "監督本文の--supervisor付きで、担当タスクの外に及ぶ操作（作成・照合・修復・Desktop更新など）を実行した",
+  action: "ユーザーの端末から--supervisorなしで、ユーザーが委任した範囲で実行する。",
+};
+
+const remoteHostUnsupportedError = {
+  code: "REMOTE_HOST_OPERATION_UNSUPPORTED",
+  when: "--hostまたはhostId付きリンクでリモートホストを指定した",
+  action: "Mac上のDesktopを直接操作するコマンドで、リモートには使えない。ローカルDesktopを対象にするときだけ--hostなしで実行する。何も実行されていない。",
+};
+
+const desktopUiFailedError = {
+  code: "DESKTOP_UI_FAILED",
+  when: "Desktopを開く・画面を操作する処理（open・osascript）が失敗した",
+  action: "error.messageを確かめ、ユーザーにDesktopの状態と端末のAccessibility権限の確認を依頼する。自動で再試行しない。",
+};
+
+const remoteContextError = {
+  code: "REMOTE_CONTEXT_REQUIRED",
+  when: "pairedのリモートで作成・表示するのに、呼出し元のローカルチャット（--context-threadまたはCODEX_THREAD_ID）がない",
+  action: "保存済みターンのある実在ローカルチャットのUUIDを--context-threadで渡す（Codex内ではCODEX_THREAD_IDが使われる）。",
+};
+
+export const topics = {
+  overview: {
+    title: "別のAIと、Codexタスクの進行を共有する",
+    when: "タスクを探す → 現状を読む → 指示を送る → 変化を確認する、という順で使う。目的に合うトピックを下の一覧から選び、codexteer help <TOPIC>で詳細を読む。",
+    use_cases: [
+      { need: "プロジェクトと目標だけを渡し、担当編成から統合まで任せる", command: "help orchestrate" },
+      { need: "その初期プロンプト本文だけを取得する（起動しない）", command: "help orchestrate prompt" },
+      { need: "既存タスクにClaudeまたはCodex CLIの監督役を付けて起動・一時停止・停止する", command: "help supervise" },
+      { need: "監督役（オーケストレーター）へ渡す本文だけを取得する（起動しない）", command: "help supervise prompt" },
+      { need: "監督の観測→介入→結果確認の手順、Claude CodeのMonitorから使う", command: "help monitor" },
+      { need: "指摘・解決条件・評価を追跡し、同じ指摘の重複介入を防ぐ", command: "help findings" },
+      { need: "作成先プロジェクトのIDとソースフォルダを調べる", command: "help projects" },
+      { need: "送信先タスクのIDを探す", command: "help threads" },
+      { need: "初回指示付きでタスクを作る・作成結果を照合する・URLをIDにする・残留ターンを修復する", command: "help thread" },
+      { need: "実行中・停止中・承認待ちかを確認する", command: "help status" },
+      { need: "発言・コマンド・変更ファイルと前回からの差分を読む", command: "help read" },
+      { need: "変化・完了・ユーザー対応待ちまで待つ", command: "help watch" },
+      { need: "方針・レビュー・仮説を根拠付きで送る", command: "help send" },
+      { need: "送った指示が届いたか・対応されたかを確認する", command: "help history" },
+      { need: "古い診断や指示を訂正・撤回する", command: "help instructions" },
+      { need: "テストしたソースと結果・成果物を照合する", command: "help checkpoint" },
+      { need: "画面・Unity・Gitなどの利用を複数AIで調整する", command: "help resource" },
+      { need: "接続（shared/desktop/cloud/desktop-cloud）を選ぶ・接続とIDの不一致を直す", command: "help connection" },
+      { need: "接続・実行環境・互換性を診断する", command: "help doctor" },
+      { need: "Desktopをwrapper付きで起動・更新する", command: "help desktop" },
+      { need: "タスクを画面で開く", command: "help open" },
+      { need: "UI送信のために画面構造を診断する", command: "help debug-ui" },
+      { need: "Web Cloud（task_ ID）の環境とタスクを使う", command: "help cloud" },
+      { need: "Cloudタスクの記録済み差分を見る", command: "help diff" },
+      { need: "Desktop Cloud（durable_ ID）を使う", command: "help desktop-cloud" },
+      { need: "Desktop Cloudの実行環境を一覧する", command: "help environments" },
+      { need: "別ホスト（hostId付きリンク）のプロジェクト・タスクを扱う", command: "help remote" },
+      { need: "Remote Controlで既存のactiveターンへ指示する", command: "help remote-control" },
+      { need: "codexteer専用の端末鍵を登録・ペアリングする", command: "help remote-device" },
+      { need: "この目的別一覧と全コマンドの概要を表示する（このページ）", command: "help overview" },
+    ],
+    usage: [
+      "help [TOPIC]",
+      "projects list",
+      "threads list [--desktop-only] [--limit N]",
+      "thread create --project ID|NAME [--context-thread THREAD-ID] <MESSAGE>",
+      "thread verify <ATTEMPT-ID>",
+      "thread resolve <THREAD>",
+      "status <THREAD>",
+      "read <THREAD> [--since CURSOR] [--limit N]",
+      "watch <THREAD> [--since CURSOR] [--until change|idle|attention]",
+      "send <THREAD> <MESSAGE...> [--new-turn] [--dry-run] [--no-sound]",
+      "history list|show|check|mark <THREAD> ...",
+      "instructions list|retract <THREAD> ...",
+      "findings create|list|show|resolve|dismiss|reopen|evaluate|stats <THREAD> ...",
+      "checkpoint capture|run|attach|verify|list|show <THREAD> ...",
+      "resource acquire|status|list|renew|release|run ...",
+      "supervise <THREAD> [MESSAGE] [--agent claude|codex] [--connection shared|desktop|cloud|desktop-cloud] [--use-path-cli] [-- <AGENT-ARGS...>]",
+      "supervise prompt <THREAD> [MESSAGE] [--agent claude|codex] [--connection shared|desktop|cloud|desktop-cloud] [--use-path-cli]",
+      "supervise status|pause|resume|stop <THREAD>",
+      "supervise list",
+      "orchestrate --project ID|NAME <GOAL> [--agent claude|codex] [--use-path-cli] [-- <AGENT-ARGS...>]",
+      "orchestrate prompt --project ID|NAME <GOAL> [--agent claude|codex] [--use-path-cli]",
+      "doctor [--backend app-server|ui]",
+      "desktop start [--dry-run]",
+      "desktop update [--dry-run] [--timeout-ms N]",
+      "desktop update-status",
+      "open <THREAD>",
+      "debug-ui <THREAD> [--wait-ms N]",
+      "diff <CLOUD_TASK_ID|URL> [--attempt N]",
+      "--connection shared|desktop|cloud|desktop-cloud <COMMAND> ...",
+      "--host HOST-ID [--remote-transport native|control|paired] <COMMAND> ...",
+    ],
+    options: [
+      { name: "TOPIC", default: "overview", text: "上の一覧のトピック名（例: send、supervise prompt）。<COMMAND> --helpでも同じ内容を表示する。" },
+    ],
+    returns: "--jsonを付けると、成功時は{ok:true, command, data}、失敗時は{ok:false, error:{message, code, …}}を標準出力へ1行で返し、失敗時の終了コードは1。対話起動のsupervise <THREAD>とorchestrate（promptなし）は--json非対応で、エージェントの標準入出力と終了コードをそのまま引き継ぐ。watch --streamは常にJSON Lines。",
+    examples: [
+      "codexteer supervise <THREAD>",
+      "codexteer supervise <THREAD> --use-path-cli",
+      "codexteer threads list --desktop-only --json",
+      "codexteer read <THREAD> --json",
+      "codexteer help send --json",
+    ],
+    notes: [
+      "THREADはDesktopのUUIDかcodex://threads/<UUID>、Web Cloudのtask_ IDか公式タスクURL、Desktop Cloudのdurable_ IDかhostId=durable付きリンク。",
+      "hostId付きのcodex://threadsリンクは別ホストのタスクを指す（help remote）。",
+      "help自体も--jsonに対応する。引数なしのcodexteerとcodexteer helpはこのoverviewを表示する。",
+      "各トピックには使い所・オプションと既定値・出力・エラーと対処・例・制約を載せている。",
+      "--connection・--host・--remote-transport・--context-threadは、どのコマンドでも -- より前に置ける。",
+      "ローカル経路の引数の誤りはerror.code=OPTIONS_INVALIDで、送信やコマンド実行の前に止まる。CloudはCLOUD_OPTIONS_INVALID。",
+      "CODEX_HOME/codex-steer/の記録の所有者・権限・種類が安全でなければSTORE_UNSAFEで止まり、自動修復しない。",
+    ],
+  },
+
+  connection: {
+    title: "--connectionで接続先を選ぶ（既定shared・観測専用desktop・cloud・desktop-cloud）",
+    when: "通常起動したDesktopを再起動せずに観測したいとき、またはタスクIDと接続の不一致で拒否されたとき。Web Cloudはhelp cloud、Desktop Cloudはhelp desktop-cloud、別ホストはhelp remote。",
+    usage: [
+      "--connection shared|desktop|cloud|desktop-cloud doctor --thread <THREAD>",
+      "--connection desktop read|status <THREAD>",
+      "--connection desktop watch <THREAD> --stream [--notify all|digest] [--settle-ms N] [--max-hold-ms N] [--since CURSOR]",
+      "supervise <THREAD> [MESSAGE] --connection desktop [--agent claude|codex]",
+      "supervise prompt <THREAD> [MESSAGE] --connection desktop [--agent claude|codex]",
+    ],
+    options: [
+      { name: "--connection shared|desktop|cloud|desktop-cloud", default: "shared", text: "全コマンド共通の接続指定。-- より前ならどこに置いてもよい。省略時だけ、task_/公式URLはcloud、durable_/hostId=durableはdesktop-cloudを自動で選ぶ。" },
+      { name: "--connection shared", text: "desktop startで起動したwrapper経由。観測・送信・作成のすべてに使う既定の接続。" },
+      { name: "--connection desktop", text: "通常起動Desktopの既存制御ソケットを読むだけの観測専用接続。" },
+      { name: "--connection cloud", text: "Web Cloud（task_ ID・chatgpt.com/codex/tasksのURL）。宛先のない一覧・作成ではこの明示が必要。" },
+      { name: "--connection desktop-cloud", text: "Desktop Cloud（durable_ ID・hostId=durableリンク）。" },
+    ],
+    returns: "--connection desktopのdoctorはconnection.mode=desktop・observation_only=trueを返し、runtime_compatibility.operationsのsend・send_new_turnはunsupported。read/status/watchのJSONは使った接続をconnection_modeで返す。不一致の拒否ではerror.expected_connection（修正候補）とerror.connection（指定値）を返す。",
+    errors: [
+      { code: "CLOUD_TARGET_CONFLICT", when: "--connectionとタスクIDの種類が合わない（例: desktopにtask_、desktop-cloudにローカルUUID）", action: "エラー文の--connectionかerror.expected_connectionの値で実行し直す。error.connectionは指定した値。自動では切り替えない。" },
+      { code: "CLOUD_OPTIONS_INVALID", when: "--connection cloudにWeb Cloud以外のID（ローカルUUID・durable_）を渡した。Cloud IDやオプションが不正なときも出る", action: "error.expected_connectionがあればその接続で実行し直す。なければIDとオプションを直す。" },
+      desktopReadOnlyError,
+      { code: "DESKTOP_CONNECTION_UNAVAILABLE", when: "CODEX_HOME/app-server-control/app-server-control.sockがない（Desktopが共有ローカルdaemonを使っていない、またはCODEX_HOMEが違う）", action: "desktop接続は使えない。CODEX_HOMEを確認するか既定sharedを使う（help desktop）。codexteerはdaemonを起動しない。" },
+      { code: "DESKTOP_CONNECTION_UNSAFE", when: "CODEX_HOME・制御ディレクトリ・ソケットの所有者・権限・種類・リンク先が検査に通らない", action: "自動修復しない。ユーザーに所有者と権限の確認を依頼する。" },
+      { code: "DESKTOP_CONNECTION_CHANGED", when: "観測の途中で制御エンドポイントが消えた・入れ替わった", action: "接続先を確認してから、改めて明示的にread/watchを始める。" },
+      { code: "DESKTOP_THREAD_NOT_LOADED", when: "対象タスクがこのDesktopのthread/loaded/listにない", action: "対応するプロフィール（CODEX_HOME）と、Desktopで読み込み済みのタスクを選ぶ。codexteerは暗黙にresumeしない。" },
+      { code: "HOST_CONNECTION_MISMATCH", when: "--hostまたはhostId付きリンクのリモート対象に--connection desktopなどを付けた", action: "--connectionを外す。リモートは選んだホストの経路で観測する（help remote）。" },
+      ...sharedRuntimeErrors,
+    ],
+    examples: [
+      "codexteer --connection desktop doctor --thread <THREAD> --json",
+      "codexteer --connection desktop read <THREAD> --include-output --json",
+      "codexteer supervise <THREAD> --agent codex --connection desktop",
+    ],
+    notes: [
+      "ID種別と接続: ローカルUUID→shared（観測だけならdesktopも可）、task_/公式URL→cloud、durable_/hostId=durable→desktop-cloud。",
+      "明示した--connectionは自動で切り替えない。sharedとdesktopの間でも、失敗時に別の接続・プロフィール・daemonへフォールバックしない。",
+      "desktopはCODEX_HOME/app-server-control/app-server-control.sockを使う。Desktopが共有ローカルdaemonを使う環境だけにあり、通常起動なら必ずあるわけではない。",
+      "CODEX_HOMEは実体パスへ解決し、本人所有でgroup/otherが書き込めないディレクトリだけを受け入れる。",
+      "app-server-controlは、group/otherの権限がない本人所有の実ディレクトリに限る。シンボリックリンクなら拒否する。",
+      "ソケットがリンクなら、公式の配置（/tmp/codex-daemon-<uid>/<リンク実体パスのsha256>、親は0700、本人所有の実ソケット）を指す場合だけ受け入れ、他は拒否する。",
+      "権限やリンクを自動修復しない。接続の前後と各API要求の前後で、エンドポイントの同一性（デバイス・inode等）を確かめ直す。",
+      "対象がthread/loaded/listにある場合だけ履歴を読む。暗黙のthread/resume、daemonの起動・再起動、設定変更はしない。",
+      "desktop接続で使えるのはread/status/watch、doctor（app-server）、threads list、thread resolve、supervise、findings・history・instructions list・checkpoint・resource。",
+      "desktop接続では送信・new-turn・UI送信・撤回送信・作成・修復と、projects・open・debug-ui・desktop・orchestrateをDESKTOP_READ_ONLYで拒否する。",
+      "通常起動Desktopでの送信・UI表示・承認の往復は実機での互換性が未検証。",
+    ],
+    see: ["doctor", "desktop", "cloud", "desktop-cloud", "remote", "supervise"],
+  },
+
+  doctor: {
+    title: "接続・実行環境・観測APIの互換性を診断する",
+    when: "接続できないとき、監督の開始時、Desktop更新後。対象タスクを読めるかまで確かめるときは--thread、UI送信の前提だけを見るときは--backend ui。",
+    usage: [
+      "doctor [--backend app-server|ui]",
+      "doctor --thread <THREAD> [--backend app-server]",
+      "--connection desktop|cloud|desktop-cloud doctor [--thread <THREAD>]",
+    ],
+    options: [
+      { name: "--thread <THREAD>", text: "指定タスクを1件だけ読み、観測経路まで検証する。app-server専用。Cloud・Desktop Cloud・hostId付きリンクも指定できる。" },
+      { name: "--backend app-server|ui", default: "app-server", text: "uiはUI送信の前提（macOS・ChatGPT.app・同梱AppleScript・端末のAccessibility権限）だけを確認する。--threadとは併用できない。" },
+      { name: "--connection shared|desktop|cloud|desktop-cloud", default: "shared", text: "診断する接続。値の意味はhelp connection。" },
+    ],
+    returns: "app-serverはready・checks・desktop_version・cli_version・cli_version_status・codex_steer_compatibility・runtime_compatibility・desktop_subscription・connection・compatibility・failure・remediationを返す。uiはready・checks・desktop_settings・remediation。readyがfalseなら終了コード1。",
+    errors: [
+      ...sharedRuntimeErrors,
+      { code: "WRAPPER_NODE_UNVERIFIED", when: "起動中のwrapperがDesktop同梱のNodeで動いていると確認できない（Appツールの署名認可が失敗しうる）", action: RESTART_SHARED },
+      { code: "RUNTIME_PROTOCOL_UNSUPPORTED", when: "wrapperが宣言した共通通信仕様の版に、このCLIが対応していない", action: "runtime_compatibility.protocolを確認し、対応するCLIを使うか、作業を終えてからwrapperを更新する（desktop start）。" },
+      { code: "RUNTIME_PROTOCOL_UNVERIFIED", when: "通信仕様の宣言が不正、または宣言のない旧環境で送信系の操作を求めた", action: "runtime_compatibility.protocolを確認し、対応するCLIを使うか、作業を終えてからwrapperを更新する（desktop start）。" },
+      { code: "CAPABILITY_UNSUPPORTED", when: "操作に必要な機能（thread_read・turn_steer・turn_start・desktop_subscribeなど）が未対応と宣言されている", action: "runtime_compatibility.operationsでsupportedの操作だけを使う。必要なら対応するCLI・wrapperにする。" },
+      { code: "CAPABILITY_UNVERIFIED", when: "機能の宣言が不正で、対応を確認できない", action: "runtime_compatibility.featuresを確認し、supportedの操作だけを使う。" },
+      { code: "DESKTOP_SUBSCRIPTION_UNAVAILABLE", when: "desktop_subscription.codeに出る。新規ターン用のDesktop購読エンドポイントがない", action: "send_new_turnだけunsupportedになる。観測と通常送信はoperationsの判定どおり使える。" },
+      desktopReadOnlyError,
+      OPTIONS_INVALID,
+    ],
+    examples: [
+      "codexteer doctor --json",
+      "codexteer doctor --thread <THREAD> --json",
+      "codexteer --connection desktop doctor --thread <THREAD> --json",
+      "codexteer doctor --backend ui --json",
+    ],
+    notes: [
+      "診断の失敗はエラー終了ではなく、failure（code・rpc_code・method、該当時はcapability）とremediationで返す。上のエラーコードはfailure.codeに入る。",
+      "readyはchecksがすべて真で失敗がないこと。checksはmacOS・同梱CLI・Desktop・runtime・初期化・同梱Node（desktop接続では省略）、--thread時はobservation。",
+      "codex_steer_compatibilityはパッケージ名と版の比較（matched/mismatch/unverified）で、違いだけではreadyに影響しない。",
+      "cli_version_statusは同梱CLIと起動中wrapperのCLIの版の一致（matched/mismatch/unverified）。",
+      "runtime_compatibilityは通信仕様（protocol）・機能（features）・操作（operations）ごとにsupported/unsupported/unverifiedを返す。",
+      "operationsはread・watch・monitor・history_check・send・send_new_turn。新規ターンだけ未対応でも、観測と通常送信はそれぞれの判定で使える。",
+      "宣言のない旧環境は読み取りをプローブで検証する。未知の送信仕様は試験送信せず、RUNTIME_PROTOCOL_UNVERIFIEDで止める。",
+      "--threadなしは接続だけを診断し、compatibility.scope=connection-only・status=unverified。--thread成功時はscope=target-observation・status=verified。",
+      "compatibility.statusはverified/unverified/unsupported/failed。verifiedは対象の初回観測の成功で、履歴全体・送信・画面表示・承認往復は保証しない。",
+      "api_checksは呼び出したAPIだけが判定され、呼び出していないAPIはunverifiedのまま。",
+      "タスク本文を診断出力に含めない。タスクの再開・送信・承認回答・Desktop再起動・設定変更はしない。",
+      "--connection cloudは環境一覧（--thread時は対象の1件読み取り）で確かめ、成功時はready:trueとCloudの操作一覧を返す。",
+      "--connection desktop-cloudは--thread時に1件読み取り、--projectを付けると所属と割当APIの可否も返す（help desktop-cloud）。",
+      "リモートでRemote Controlの認証前に止まった場合は、remote_control_authに詳細を返す（help remote-control）。",
+      "sharedが使えなくても、Desktopの制御ソケットがある環境では--connection desktopで観測だけはできる（help connection）。",
+    ],
+    see: ["connection", "desktop", "cloud", "desktop-cloud", "remote-control", "debug-ui"],
+  },
+
+  desktop: {
+    title: "Desktopをwrapper付きで起動し、公式更新後もwrapper付きで再起動する",
+    when: "既定sharedの接続を用意するとき（RUNTIME_UNAVAILABLEなど）、またはDesktopを公式更新するとき。startはDesktop終了後、updateは起動中のDesktopの作業を終えてから実行する。通常起動のまま観測だけならhelp connection。",
+    usage: [
+      "desktop start [--dry-run]",
+      "desktop update [--dry-run] [--timeout-ms N]",
+      "desktop update-status",
+    ],
+    options: [
+      { name: "--dry-run", text: "startは接続・配置・起動をせずstarted:falseを返す。updateは状態・権限も確認せず、手順（steps）とtimeout_msだけを返す。" },
+      { name: "--timeout-ms N", default: "600000", text: "updateで更新と再起動を待つ上限（ms）。10000〜3600000。" },
+    ],
+    returns: "startはstarted・desktop_version・cli_version・deployment（directory・wrapper_path・version・sha256・reused）。updateはworkerの起動受付（started・worker_pid・status_command・status_path）だけ。update-statusはphase・worker_alive・wrapper_verified、失敗時はerror（code・message）とrecovery。",
+    errors: [
+      { code: "DEPLOYMENT_BUSY", when: "配置ロック（CODEX_HOME/codex-steer/runtimes/.install-<id>）が残っている", action: "ロックは自動で奪わない。並行実行がないか確かめ、中断した配置ならロックを調べてから実行し直す。" },
+      { code: "DEPLOYMENT_MODIFIED", when: "保存済みの配置が配布物の内容と一致しない", action: "上書きしない。ユーザーに配置先の確認を依頼する。" },
+      { code: "UPDATE_APP_STATE", when: "起動中のDesktopがちょうど1つではない", action: "Desktopを1つだけ起動した状態で実行し直す。" },
+      { code: "UPDATE_COMMAND_FAILED", when: "osascript・PlistBuddy・psが失敗した（更新メニューがない・無効、Accessibility/Automation権限がないなど）", action: "メッセージを確かめ、ユーザーに端末の権限許可や更新メニューの状態確認を依頼して実行し直す。" },
+      { code: "UPDATE_UI_UNAVAILABLE", when: "事前確認でCodexの更新メニューに到達できない（Codexのプロセスが見つからないなど）", action: "ユーザーに端末のAccessibility/Automation許可を依頼して実行し直す。" },
+      { code: "UPDATE_NODE", when: "Desktop同梱のNode（.app内）でupdateを実行した", action: "外部にインストールしたNodeで実行する。" },
+      { code: "UPDATE_BUSY", when: "更新ロック（CODEX_HOME/codex-steer/desktop-update/lock）が残っている", action: "update-statusを確かめる。workerが止まっていれば、アプリを確認してからユーザーがロックを削除する。" },
+      { code: "UPDATE_TIMEOUT", when: "update-statusのerror.code。期限内に更新・再起動が終わらなかった", action: "Codexと更新画面のダイアログを確認する。プロセスは強制終了されていない。" },
+      { code: "UPDATE_QUIT_TIMEOUT", when: "update-statusのerror.code。更新後のDesktopが30秒以内に正常終了しなかった", action: RESTART_SHARED },
+      { code: "UPDATE_WRAPPER_UNVERIFIED", when: "update-statusのerror.code。更新後のdoctorでshared接続・同梱Node・CLI版一致を確認できなかった", action: "doctor --jsonで原因を確かめる。" },
+      { code: "DESKTOP_START_UNSUPPORTED", when: "startをmacOS以外で実行した、またはCODEX_APP_SERVER_WS_URLが設定されている", action: "macOSで、CODEX_APP_SERVER_WS_URLを外した環境から実行する。何も起動していない。" },
+      { code: "DESKTOP_ALREADY_RUNNING", when: "startの時点でDesktopが起動している", action: "起動中のDesktopは終了させない。ユーザーに作業を終えてDesktopを終了してもらい、desktop startを実行し直す。" },
+      { code: "DESKTOP_START_FAILED", when: "startでDesktopの起動確認（ps）か起動（open）が失敗した", action: "ユーザーの端末からdesktop startを実行し直してもらう。Dockからの通常起動はできるが、その場合sharedは使えない（観測だけならhelp connection）。" },
+      { ...RUNTIME_NOT_READY, when: "startでDesktopは起動したが、shared App Serverが準備完了にならなかった" },
+      supervisorForbiddenError,
+      remoteHostUnsupportedError,
+      desktopReadOnlyError,
+      OPTIONS_INVALID,
+    ],
+    examples: [
+      "codexteer desktop start --dry-run --json",
+      "codexteer desktop start",
+      "codexteer desktop update --json",
+      "codexteer desktop update-status --json",
+    ],
+    notes: [
+      "macOS専用。CODEX_APP_SERVER_WS_URLが設定された環境ではstartもupdateも拒否する。",
+      "start --dry-runは環境・Desktopの起動状態を確かめずに返す。",
+      "startは起動中のDesktopを終了させない。起動中ならエラーで止まる。通常起動へ戻すには、終了後にDockなどから開き直す。",
+      "startは呼び出した配布物をCODEX_HOME/codex-steer/runtimes/<version>-<sha256>へ検証して置き、そのwrapperをCODEX_CLI_PATHに指定してDesktopを開く。",
+      "配置先の所有者・権限・リンク・内容を検証し、既存の配置は上書きしない。同じ内容なら検証して再利用する（deployment.reused）。",
+      "startは起動後、今回の配布物のwrapperが動きshared App Serverへ接続できることまで確かめて返る。",
+      "npxで使うパッケージ名はcodexteer。通常は版指定なしでよく、特定の版で始めたいときだけcodexteer@<版>とする。",
+      "起動したwrapperと操作するCLIの製品版が違っても、通信・機能仕様が対応していれば使える（doctorのruntime_compatibility）。",
+      "updateは公式の更新メニューと更新ボタン（英語・日本語のラベル）をAccessibilityで操作し、残りを外部Nodeの独立プロセス（worker）で続ける。",
+      "updateは既知のラベルを照合するだけで、更新ウィンドウ自体の真正性は確かめない。更新以外のダイアログは閉じておく。",
+      "ラベル不一致やOSの許可ダイアログでは自動操作を進めず、時間切れで止まる。Desktopを強制終了しない。",
+      "updateは新しいビルドとプロセスに替わったことを確かめてからDesktopを正常終了させ、wrapper付きで起動し、doctorで確認する。",
+      "起動受付は完了ではない。update-statusでphase=completeかつwrapper_verified=trueを確認する。",
+      "既に最新ならphase=up_to_dateで終わり、再起動しない（wrapper_verified=false）。",
+      "update-statusはCODEX_HOME/codex-steer/desktop-update/status.jsonを読む。未実行ならphase=not_started。",
+    ],
+    see: ["connection", "doctor"],
+  },
+
+  projects: {
+    title: "登録プロジェクト（ローカル・リモート登録・接続先・Cloud環境）を一覧する",
+    when: "thread createの--projectに使うIDを調べるとき、チャットの所属・ソースフォルダ・ホストを確認するとき。",
+    usage: [
+      "projects list [--remote | --all] [--host HOST-ID]",
+      "--host HOST-ID --remote-transport paired projects list",
+      "--connection cloud projects list",
+      "--connection desktop-cloud projects list",
+    ],
+    options: [
+      { name: "--remote", text: "CODEX_HOMEにあるDesktopのリモート登録だけを読む。--allとは併用できない。" },
+      { name: "--all", text: "ローカル一覧とリモート登録を併合する。--hostとは併用できない。" },
+      { name: "--host HOST-ID", text: "そのホストのリモート登録に絞る。--remote-transport pairedなら接続先のproject/listを読む。" },
+    ],
+    returns: "projectsとcount。ローカルはApp Serverのcanonical ID（project_id）・desktop_project_ids・name・全roots。リモートはproject_kind:remote・host_id・source・availabilityも返す。テキストは1行目にIDと名前、続く行に各root。",
+    errors: [
+      ...sharedRuntimeErrors,
+      desktopReadOnlyError,
+      { code: "PROJECT_REGISTRY_UNSAFE", when: "CODEX_HOME/.codex-global-state.jsonが本人所有の通常ファイルでない、またはgroup/otherが書き込める", action: "自動修復しない。ユーザーにファイルの所有者と権限の確認を依頼する。" },
+    ],
+    examples: [
+      "codexteer projects list --json",
+      "codexteer projects list --remote --json",
+      "codexteer projects list --all --json",
+      "codexteer projects list --host remote-control:env_example --json",
+      "codexteer --connection cloud projects list --json",
+    ],
+    notes: [
+      "引数なしのローカル一覧はshared wrapperのApp Server（project/list）を読む。desktop startで起動していないとRUNTIME_UNAVAILABLE。",
+      "--remoteとpaired以外の--hostは、CODEX_HOME/.codex-global-state.jsonのDesktop登録を読むだけで、状態ファイルは変更しない。",
+      "登録一覧のsourceはdesktop-registration、availabilityはunverified。登録はホストの接続や現存を意味しない。",
+      "pairedの--host指定は接続先のproject/listを読み、live ID・source:remote-app-server・availability:verifiedを返す。rootsの存在は未確認（roots_availability）。",
+      "pairedの結果のdesktop_project_idsは同じrootsを持つDesktop登録のIDで、pairedのthread createに使える。docs/remote-operations.md。",
+      "Windows/UNCパスをローカルパスへ変換しない。",
+      "Desktopのnative一覧はリモートのGitメタデータ取得に失敗した項目を省くため、完全な登録一覧とは扱わない。",
+      "同名のローカルプロジェクトが複数あるときはproject_idで選ぶ（名前ではPROJECT_AMBIGUOUS）。",
+      "--connection cloudはCloud環境（ID・名前・リポジトリと既定ブランチ）を返す。詳細はhelp cloud。",
+      "--connection desktop-cloudはDesktopの正規プロジェクトをdesktop_project_idごとに返す。Cloud環境の一覧はhelp environments。",
+    ],
+    see: ["thread", "remote", "cloud", "desktop-cloud", "environments"],
+  },
+
+  threads: {
+    title: "送信先タスクのIDとリンクを探す",
+    when: "宛先の正確なIDやhostId付きリンクを確認するとき。本文は読まないため、内容を見るときはread。",
+    usage: [
+      "threads list [--desktop-only] [--limit N]",
+      "--host HOST --remote-transport paired threads list [--cursor CURSOR] [--project ID] [--search TEXT]",
+      "--connection cloud threads list [--limit N] [--cursor CURSOR] [--env ENV_ID]",
+      "--connection desktop-cloud threads list [--limit N] [--cursor CURSOR]",
+    ],
+    options: [
+      { name: "--limit N", default: "20", text: "返す最大件数。ローカル・paired・cloudは1〜500、desktop-cloudは1〜100。" },
+      { name: "--desktop-only", text: "originatorがCodex Desktopのタスクだけを返す（ローカル・paired）。" },
+      { name: "--cursor CURSOR", text: "前回のnext_cursor/cursorから続きを読む。paired・cloud・desktop-cloudのみ。" },
+      { name: "--project ID / --search TEXT", text: "pairedの接続先で、プロジェクトIDまたは検索語で絞る。" },
+      { name: "--env ENV_ID", text: "cloudで環境IDに絞る。" },
+    ],
+    returns: "threadsとcount。ローカルはthread_id・updated_at・created_at・cwd・originator・deep_link。pairedはtitle・project_id・hostId付きdeep_link・next_cursor・has_moreも返す。cloudはtask_id・title・status・url・cursor・has_more。ローカル・pairedのテキストは1行1件（ID・更新日時・作業場所）。",
+    errors: [
+      { code: "REMOTE_READ_ONLY", when: "既定nativeのリモート（--host）で一覧した", action: "--remote-transport pairedを明示する。専用登録とペアリングが必要（help remote-device）。経路は自動で切り替えない。" },
+      OPTIONS_INVALID,
+    ],
+    examples: [
+      "codexteer threads list --desktop-only --limit 20 --json",
+      "codexteer --connection cloud threads list --limit 50 --json",
+    ],
+    notes: [
+      "ローカルはCODEX_HOME/sessions配下の保存履歴を更新の新しい順に調べ、各ファイル先頭のsession_metaだけを読む。本文は読まない。",
+      "ローカル一覧はApp Serverへ接続しないため、Desktopやwrapperが起動していなくても使える。",
+      "--cursor・--project・--searchはローカルでは使えない（pairedのリモートが必要）。",
+      "cloudは公式CLIの一覧からID・URL・名前・状態とページcursorを返す。本文は読まない。",
+    ],
+    see: ["read", "thread", "projects", "remote", "cloud", "desktop-cloud"],
+  },
+
+  thread: {
+    title: "タスクを作成・作成結果を照合し、IDの解決と残留ターンの修復を行う",
+    when: "プロジェクトに初回指示付きの新しいタスクを作るとき、作成済みreceiptを照合し直すとき、URLをIDへ変換するとき、古いターンが実行中のまま残ったとき。Web Cloudの作成はhelp cloud、Desktop Cloudはhelp desktop-cloud。",
+    usage: [
+      "thread create --project ID|NAME [--context-thread THREAD-ID] [--timeout-ms N] [--title TEXT] [--model MODEL] [--thinking EFFORT] [--dry-run] <MESSAGE...>|-",
+      "thread verify <ATTEMPT-ID> [--timeout-ms N]",
+      "thread resolve <THREAD>",
+      "thread repair <THREAD> [--dry-run | --apply]",
+      "--connection cloud thread create --project ENV_ID_OR_NAME [--branch BRANCH] [--dry-run] <MESSAGE...>|-",
+      "--connection cloud thread receipt <ATTEMPT_ID>",
+      "--connection desktop-cloud thread create --environment ID|NAME [--title TEXT] [--dry-run] <MESSAGE...>|-",
+      "--connection desktop-cloud thread assign TARGET --project ID|NAME",
+      "--connection desktop-cloud thread receipt <ATTEMPT_ID> [--resolve-unknown --note TEXT]",
+    ],
+    options: [
+      { name: "--project ID|NAME", text: "作成先。projects listのproject_id、desktop_project_idsのID、または完全一致の名前。cloudでは環境IDか名前。" },
+      { name: "<MESSAGE...>|-", text: "初回指示。複数の語は空白でつなぐ。- は標準入力。--で始まる本文は -- の後に置く。" },
+      { name: "--context-thread THREAD-ID", text: "ローカルで指定したときだけ、そのチャットを呼出し元にDesktopのnative create_threadで作る。省略するとstandalone作成。" },
+      { name: "--title TEXT", text: "タスク名（空は不可）。standaloneで省略すると、初回指示の空白をまとめた先頭80文字。" },
+      { name: "--model MODEL", text: "モデルを明示する（空は不可）。" },
+      { name: "--thinking EFFORT", text: "none|minimal|low|medium|high|xhigh|max|ultra。" },
+      { name: "--timeout-ms N", default: "120000", text: "create・verifyの各RPCの待機上限（ms）。1000〜600000。" },
+      { name: "--dry-run", text: "createは接続・プロジェクト・native schemaを読んで確かめるだけで、タスク・指示・記録を作らない。repairは既定でこのモード。" },
+      { name: "--apply", text: "repairで候補へ終了記録を追記する。全Codexを終了してから外部ターミナルで実行する。" },
+      { name: "--branch BRANCH", text: "cloud作成のブランチ。省略時は環境のリポジトリが1つならその既定ブランチ。" },
+      { name: "--environment ID|NAME", text: "desktop-cloud作成のCloud環境（help desktop-cloud）。" },
+    ],
+    returns: "createはthread_id・deep_link、project_id・desktop_project_id・project_name、cwdと全フォルダ、title、creation_status・delivery_status・verification_status、attempt_id・receipt_path。verifyは更新したreceiptとverification_history。resolveはthread_idとdeep_link。repairはmode・status・candidates・source_sha256、--apply成功時はbackup_path・receipt_path・repaired_sha256。",
+    errors: [
+      { code: "PROJECT_NOT_FOUND", when: "--projectに一致するプロジェクトがない", action: "projects listでIDか完全一致の名前を選ぶ。" },
+      { code: "PROJECT_AMBIGUOUS", when: "同名のプロジェクトが複数ある", action: "projects listのproject_idで指定する。" },
+      { code: "INVALID_CREATION_OPTIONS", when: "cwd・権限・承認設定の上書き、空の--title/--model、不正な--thinking・--timeout-msを指定した", action: "上書きは非対応。値を直して実行し直す。" },
+      { code: "DESKTOP_PROJECT_MAPPING_UNVERIFIED", when: "選んだプロジェクトをDesktopのプロジェクトへ一意に対応付けられない", action: "creation_statusを確かめる。desktop_project_idsが複数なら、そのIDの一つを--projectに指定する。" },
+      { code: "DESKTOP_SUBSCRIPTION_UNAVAILABLE", when: "standalone作成に必要なDesktop購読エンドポイントがない", action: `creation_statusを確かめる（not_createdなら未作成）。${RESTART_SHARED}` },
+      { code: "NATIVE_CREATION_UNKNOWN", when: "作成要求の後にタスクIDを確認できなかった", action: "自動で再作成しない。receipt_pathとDesktop上のタスクを確かめる。unknownは未作成の証拠ではない。" },
+      { code: "INITIAL_TURN_UNCONFIRMED", when: "タスクは作られたが初回ターンの受付を確認できない", action: "再送しない。thread_idのタスクをreadで確かめる。" },
+      { code: "CREATION_VERIFICATION_FAILED", when: "作成後またはverifyで、所属・フォルダ・タイトル・初回指示の照合に通らない", action: "再作成・再送しない。verification_checksを見て、時間をおいてthread verify <ATTEMPT-ID>で照合し直す。" },
+      { code: "CREATION_RECEIPT_UNVERIFIED", when: "thread verifyの対象がcreated・accepted以外（unknown・未受付・dry-run）のreceipt", action: "verifyは使えない。既存のタスクを確かめる。このコマンドは作成も再送もしない。" },
+      { code: "REPAIR_REQUIRES_OFFLINE", when: "--apply時にCodex/ChatGPT・Codex CLI/app-serverのプロセスが動いている", action: "ユーザーにすべて終了してもらい、外部ターミナルで実行し直す。codexteerはプロセスを止めない。" },
+      { code: "REPAIR_RUNTIME_UNVERIFIED", when: "同梱Codex CLIの版が修復の検証済み版でない", action: "修復できない。履歴は変更されていない。" },
+      { code: "REPAIR_LATEST_UNFINISHED", when: "--apply時に最新のターンにも終了記録がない", action: "最新ターンを通常の方法で止めてから実行し直す。" },
+      remoteContextError,
+      supervisorForbiddenError,
+      desktopReadOnlyError,
+      OPTIONS_INVALID,
+    ],
+    examples: [
+      "codexteer thread create --project 'サンプル' '関連リポジトリを読み、調査結果を報告してください' --json",
+      "codexteer thread create --project 'サンプル' --dry-run '調査してください' --json",
+      "codexteer thread verify <ATTEMPT-ID> --json",
+      "codexteer projects list --json",
+      "codexteer thread resolve codex://threads/<UUID> --json",
+      "codexteer thread repair <THREAD> --json",
+      "codexteer thread repair <THREAD> --apply --json",
+    ],
+    notes: [
+      "以下はローカルDesktopとpairedの説明。Web Cloudの作成はhelp cloud、Desktop Cloudの環境指定・作成・所属割当はhelp desktop-cloud。",
+      "standalone作成（--context-threadなし）はプロジェクトと初回指示だけで作れる。既存チャット・CODEX_THREAD_ID・中継AIは使わない。ローカル専用。",
+      "standaloneはApp Serverで全フォルダ付きのタスクを作り、Desktop購読を確立して初回指示を送り、その新タスク自身のthread/turn IDでDesktopの所属登録をする。",
+      "--context-thread指定時は、保存済みターンのある実在ローカルチャットを呼出し元にnative create_threadを使う。そのチャットへの送信や追加のAIターンはない。",
+      "pairedのリモート作成は、実在ローカルcaller（--context-threadかCODEX_THREAD_ID）でDesktop公式createを使い、接続先で照合する。docs/remote-operations.md。",
+      "モデル・権限・承認設定はプロジェクトのApp Server設定に従う。cwd・権限・承認の上書きと旧--via-threadは非対応。",
+      "CLI終了後の承認はDesktopが扱い、codexteerは自動回答しない。",
+      "タイトル用のAIは起動しない。standaloneの既定タイトルもJSONとreceiptに入る（title_source）。",
+      "作成後、Desktop native一覧のID・local host・所属、canonical projectId、全フォルダ、保存された初回指示とタイトルを照合する。旧状態ファイルの所属mapだけでは判定しない。",
+      "履歴への反映待ちは読み取りだけで行う。手順と検証範囲はdocs/thread-create.md。",
+      "作成・初回配送は自動で再試行しない。creation_status・thread_id・receipt_path・native_call_idを確かめ、createdなら既存IDを使う。",
+      "unknown・dispatchingは未作成の証拠ではない。Desktop・DB・保存履歴を直接編集しない。",
+      "receiptはCODEX_HOME/codex-steer/creations/<ATTEMPT-ID>.jsonに保存する。",
+      "thread verifyはcreated・accepted済みのreceiptだけを照合し、更新するのはcodexteerのreceiptだけ。Desktopは読み取りのみで、作成・移動・再送・AIターンは起きない。",
+      "verifyは初回本文のSHA256・文字数とstandaloneの初回turn IDも照合する。native一覧の最新50件と全pinnedに対象がなければ、成功と推測せず失敗にする。",
+      "Cloudのthread receiptは作成結果のローカル記録を返すだけ。タスクIDが不明でも試行IDで確かめられ、再作成・外部照会はしない。",
+      "Desktop Cloudのthread receipt・thread assignは受付不明の割当試行をDesktopの状態で確かめ直す。ユーザーだけが--resolve-unknownで解除できる（help desktop-cloud）。",
+      "resolveはID書式だけを検査してthread_idとdeep_linkを返す。タスクの存在確認はstatusを使う。",
+      "repairはローカル保存履歴の検査。後続の独立したターン開始があり、終了記録がない古いターンだけを候補にする。最新の未完了ターンは修復しない。",
+      "--applyは稼働中・検査不能なら拒否し、プロセスを終了させない。完了するまでCodexを起動しない。macOS専用。",
+      "--applyは検証済みのCodex CLI 0.162.0-alpha.17.2 / 0.164.0-alpha.11.1と、ordinalが連続した履歴に限る。",
+      "原本をCODEX_HOME/codex-steer/turn-repairs/へバックアップし、候補IDのturn_abortedだけを末尾へ追記する。既存の会話・ordinal・DBは書き換えない。",
+      "実際の停止時刻や所要時間は推定しない。履歴のバックアップ分の空き容量を確保しておく。",
+      "中断・検証失敗ではbackup_pathとreceipt_pathを残す。原本への上書き復元や再実行を盲目的にせず、記録を確かめる。",
+      "成功は追記とSHA256照合の成功。Codexは次のロード時に反映する。再起動後の表示と次ターンは別に確かめ、read/watchの古いcursorは更新する。",
+      "リモートではrepairできない（REMOTE_REPAIR_UNSUPPORTED）。paired以外のリモートで使えるのはresolveだけで、他はREMOTE_READ_ONLY。",
+    ],
+    see: ["projects", "threads", "status", "read", "cloud", "desktop-cloud", "remote"],
+  },
+
+  open: {
+    title: "タスクを画面（DesktopまたはWebブラウザ）で開く",
+    when: "ユーザーが画面でタスクを見たいとき。観測や送信には不要（read・sendは画面を使わない）。",
+    usage: [
+      "open <THREAD>",
+      "--host HOST-ID --remote-transport paired --context-thread LOCAL-UUID open <THREAD>",
+    ],
+    returns: "thread_idとdeep_link。ローカル・pairedのテキストは「Opened <deep_link>」。Desktop Cloudはdeep_linkだけを返す。",
+    errors: [
+      desktopReadOnlyError,
+      { code: "CLOUD_CAPABILITY_UNSUPPORTED", when: "macOS以外でCloudタスクを開こうとした", action: "thread resolveでURLを取得し、ユーザーにブラウザで開いてもらう。" },
+      { code: "CLOUD_OPEN_FAILED", when: "Cloudタスクのブラウザ起動に失敗した", action: "thread resolveでURLを取得し、ユーザーにブラウザで開いてもらう。" },
+      { code: "REMOTE_MANAGEMENT_TRANSPORT_REQUIRED", when: "リモートのタスクを既定nativeまたはcontrolで開こうとした", action: "--remote-transport pairedを明示する。" },
+      remoteContextError,
+      { code: "HOST_MISMATCH", when: "リンクのhostIdと--hostが違う、またはDesktopが選んだホストのタスクを一意に特定できない", action: "正しいホストのリンクを使う。タスクは開かれていない。" },
+      { ...desktopUiFailedError, when: "ローカルのタスクをDesktopで開くopenコマンドが失敗した" },
+    ],
+    examples: [
+      "codexteer open <THREAD>",
+      "codexteer open task_example --json",
+    ],
+    notes: [
+      "ローカルはcodex://threads/<UUID>をDesktopで開き、Desktopが前面に出る。",
+      "Cloudは公式タスクURL（https://chatgpt.com/codex/tasks/<ID>）を既定ブラウザで開く。macOSのみ。",
+      "Desktop Cloud（durable_）はhostId=durableのdeep_linkを返すだけで、アプリもブラウザも開かない。",
+      "pairedのリモートは、制御側Desktopのnative操作で対象チャットへ移動して表示する。",
+      "画面を開くための明示的なコマンドで、送信や承認回答はしない。",
+    ],
+    see: ["thread", "debug-ui", "cloud", "remote"],
+  },
+
+  "debug-ui": {
+    title: "UI送信（--backend ui）のためにDesktopの画面構造を調べる",
+    when: "明示的なUI送信方式（send --backend ui）の不具合を診断するとき。通常のバックグラウンド送信（app-server）には不要。",
+    usage: ["debug-ui <THREAD> [--wait-ms N]"],
+    options: [
+      { name: "--wait-ms N", default: "1500", text: "Desktopを前面に出してから調べるまでの待ち時間（ms）。0〜30000の整数。" },
+    ],
+    returns: "thread_id・backend:desktop-ui・accessibility_mode（manual/enhanced/unchanged）・diagnostic（ウィンドウ名、フォーカス要素のrole等、テキスト領域・入力欄・Webエリアの数）。テキストはdiagnosticだけ。",
+    errors: [
+      { code: "DESKTOP_UI_NOT_READY", when: "UI操作の前提（macOS・ChatGPT.app・同梱AppleScript・端末のAccessibility権限）が欠けている。画面は操作していない", action: "doctor --backend ui --jsonで欠けている項目を確かめ、ユーザーに対応を依頼する。" },
+      desktopUiFailedError,
+      desktopReadOnlyError,
+      remoteHostUnsupportedError,
+      OPTIONS_INVALID,
+    ],
+    examples: [
+      "codexteer debug-ui <THREAD> --wait-ms 1500",
+      "codexteer doctor --backend ui --json",
+    ],
+    notes: [
+      "画面を操作する: 対象チャットの入力欄を開くリンクでDesktopを前面に出し、フォーカス中の要素を読む。送信はしない。",
+      "調べる間だけDesktopのAccessibility属性を有効にし、終了時に元へ戻す。",
+      "先にdoctor --backend uiと同じ前提（macOS・ChatGPT.app・同梱AppleScript・端末のAccessibility権限）を確かめ、欠けていればDESKTOP_UI_NOT_READYで止まる。",
+    ],
+    see: ["doctor", "send", "open"],
+  },
+};