codexteer 0.17.0 → 0.18.0

package/docs/remote-operations.md

@@ -0,0 +1,89 @@
+# リモートのCLI操作
+
+`--host <HOST-ID> --remote-transport paired`で、接続先のタスクをcodexteer CLIから操作できます。接続先にはCodex Desktopと公式ペアリングが必要で、codexteerやCodex CLIの追加インストールは不要です。ローカルのshared wrapperと専用鍵は従来どおり使用します。既定のnative経路は観測専用、既存Desktop鍵のcontrol経路は別機能のままです。失敗時に別ホスト・別資格情報・別backendへ自動切替しません。
+
+## 対応範囲
+
+| ローカルの操作 | pairedでの動作 |
+| --- | --- |
+| `projects list` | 接続先の`project/list`で正式ID・全rootsを取得。Desktop登録IDも別フィールドで対応付ける |
+| `threads list` | 接続先のタスクID・タイトル・所属・作業場所・hostId付きリンクを取得。ページ・検索・project指定・Desktop絞込みに対応 |
+| `thread create` | Desktopの公式createで対象ホストへ作成し、pairedでcanonical所属・初期指示・全rootsを照合 |
+| `thread verify` | 保存済みremote receiptを読み直して照合。作成・初期送信・所属変更は繰り返さない |
+| `thread resolve` | hostIdを保持してIDを解決 |
+| `read/status/watch/doctor` | 選択先の履歴・稼働状態・差分・接続を読む |
+| `send` | 実行中の同じターンへ`expectedTurnId`付きで一度だけ送る |
+| `send --new-turn` | idleだけを対象とし、制御側Desktopで対象チャットを開いてから同じ接続先へ`turn/start`する |
+| `supervise`・findings・history・instructions | 従来のpause/stop・freshness・重複防止・受信照合を維持。記録・ロックはホストごとに分離 |
+| `orchestrate` / `orchestrate prompt` | 接続先host・paired・callerを子作成/監督コマンドへ保持。エージェント自体は制御側で動く |
+| `checkpoint capture/verify/attach`・ファイル根拠 | 接続先の公式`fs/*`で読む。相対入力パスは対象チャットのcwdで解決。ファイル根拠・artifactはリモート絶対パス |
+| `checkpoint run`・`resource run` | defaultは接続先の`command/exec`。明示的な`thread-shell`にも対応（下記）。Macでは実行しない |
+| resourceの取得・更新・解放・一覧 | ホスト別の協調記録。OSの排他制御を作るものではない |
+| `open` | 制御側Desktopで指定したリモートチャットを表示 |
+| `desktop start/update/update-status`・`debug-ui` | Macの起動/更新/Accessibility用で接続先へは未対応。ローカルで誤実行せず`REMOTE_HOST_OPERATION_UNSUPPORTED` |
+| `thread repair` | 修復機能はローカル専用。リモート指定は`REMOTE_REPAIR_UNSUPPORTED`で明示拒否し、保存履歴やDBを変更しない |
+| `--backend ui` | 接続先のUI送信は未対応。明示的に拒否する |
+
+Macの起動・更新・Accessibilityとオフライン履歴修復は、リモート接続先へ提供していません。上表は実装範囲であり、接続先APIが全操作を許可する保証でもありません。
+
+## 一覧と作成
+
+```sh
+codexteer --host remote-control:env_example --remote-transport paired projects list --json
+codexteer --host remote-control:env_example --remote-transport paired threads list --limit 20 --json
+codexteer --host remote-control:env_example --remote-transport paired threads list --project CANONICAL-ID --search 検証 --json
+codexteer --host remote-control:env_example --remote-transport paired threads list --cursor CURSOR --json
+codexteer --host remote-control:env_example --remote-transport paired --context-thread LOCAL-CALLER-ID thread create --project PROJECT-ID --title 検証専用 '初回の指示' --json
+codexteer --host remote-control:env_example --remote-transport paired thread verify ATTEMPT-ID --json
+```
+
+`project_id`は接続先App Serverの正式ID、`desktop_project_ids`は制御側Desktopの登録IDです。両者を同じIDとは扱いません。登録ID・正式ID・一意の正確な名前で作成対象を選べます。Desktopの登録とlive projectの全rootsが一意に一致しなければ作成しません。Windows/UNCをMacのパスへ変換したり、Macのrealpath/statで検査したりしません。
+
+paired一覧の`availability: verified`は`availability_scope: project-catalog`です。ホストへ接続して正式一覧を読めた意味で、各rootの現在の存在・読み書き可否は`roots_availability: unverified`です。
+
+作成はDesktopの公式native APIを使うため、**実在するローカルcallerと保存済みturnが必要**です。Codex内では`CODEX_THREAD_ID`を使用し、通常の端末からは`--context-thread LOCAL-CALLER-ID`を明示します。callerの追加ターンやAIによる中継は作りません。pairedの一覧・read・通常sendにはcallerは不要です。ローカルstandalone作成は従来どおりcaller不要で、環境変数も継承しません。
+
+`--dry-run`はnative schema・live project・登録の対応を検査するだけで、作成・送信・receipt保存をしません。作成後は実ホスト、Desktop所属とcanonical所属、タイトル、初回本文、project rootsを照合します。Desktopが付与するそのタスク固有のvisualizations rootだけは、同じprofile・履歴日・thread IDから照合して許容し、それ以外の追加rootは拒否します。
+
+POSIXパスの大文字小文字は区別します。Windowsのドライブ付きパスとバックスラッシュのUNCパスだけは、Windowsの表記を正規化して照合します。再照合が失敗した場合はreceiptのverificationをfailedへ更新して古い認定フラグを除去し、created/acceptedは保持します。
+
+`creation_status: created`は既存タスクがある状態です。後段の照合失敗でもそのIDとacceptedを保持します。応答不明はunknownとしてreceiptを残し、自動再作成・再送しません。異なるホストが返った場合も判明したIDを保持して停止し、そのタスクへ追加操作しません。
+
+## 新しいターンと監督
+
+```sh
+codexteer --remote-transport paired --context-thread LOCAL-CALLER-ID send 'codex://threads/UUID?hostId=remote-control%3Aenv_example' '続きの指示' --new-turn --json
+codexteer --remote-transport paired --context-thread LOCAL-CALLER-ID supervise prompt 'codex://threads/UUID?hostId=remote-control%3Aenv_example' --use-path-cli --json
+```
+
+new-turnは、実在callerによるDesktop native readでthread/hostを照合し、公式navigation APIで制御側Desktopに対象チャットを表示します。通常sendと異なり画面遷移があり、そのDesktopの持続する接続で対象を開いた後、pairedでidle・freshnessを再確認して一度だけ`turn/start`します。短命なsenderだけでresumeする経路は使いません。ユーザーからの再開委任がないidleタスクを監督目的だけで再開しません。
+
+生成する監督・オーケストレーションコマンドはhost・transport・指定callerを保持します。停止済みの監督を別ID・unbound送信で迂回しません。承認・質問を自動回答するAPIは追加していません。画面への吹き出し表示や承認UI往復は、受付・保存・明示応答とは別の検証項目です。
+
+## リモートの検証コマンド
+
+既定の`command/exec`は接続先の設定された権限を使い、sandbox/permissionの上書きを送りません。接続先によってはこのAPIが`RPC_REJECTED`（-32600）になる場合があります。この拒否から自動で別経路を試しません。
+
+公式`thread/shellCommand`は**ホストのfull accessでシェルを実行**するAPIです。その意味を選べるよう、次の明示指定に限定します。
+
+```sh
+codexteer --host remote-control:env_example --remote-transport paired resource run test-resource --owner codex --thread TEST-THREAD-ID --exec-backend thread-shell --shell powershell --cwd 'C:\Windows' --timeout-ms 10000 --include-output -- cmd.exe /d /c 'echo test'
+codexteer --host remote-control:env_example --remote-transport paired checkpoint capture TEST-THREAD-ID tests --path 'C:\test\input.txt' --json
+codexteer --host remote-control:env_example --remote-transport paired checkpoint run TEST-THREAD-ID CHECKPOINT-ID --exec-backend thread-shell --shell powershell --timeout-ms 10000 --include-output -- cmd.exe /d /c 'echo test'
+```
+
+`--shell powershell|posix`が必須で、相手のshellを推測しません。resourceでは対象`--thread`も必須、checkpointは自身のthreadを使います。idle以外では実行しません。argvは選んだshellの規則で引用し、任意のshell式として連結しません。`cmd.exe /c`などに式を渡す場合は、その式自体が明示したユーザーのコマンドです。
+
+受け付けたという空応答だけでは成功としません。ランダムIDを含む実行項目、集約出力中の独立した1行に一度だけ現れる完了marker（stdoutのmarker後にstderrが続く場合も許容）、同じ項目のexitCodeを接続先の保存履歴で照合します。人間/モデルの「成功した」という発言では判定しません。full access・backend・実行先・終了コードを結果に表示します。制御側Macのプロセスを起動しません。
+
+リモートのtimeout 0はthread-shellで公式APIの既定に合わせ1時間、汎用command/execで24時間として送ります（ローカルの無制限とは異なります）。明示timeoutは最大24時間です。thread-shellには対応する限定的な取消操作がないため、観測中断時に別のCodex作業を止める操作は行いません。完了を照合できない場合はunknown・再送禁止とし、resourceは期限までleaseを保持、checkpointは無効にします。承認/質問への代理回答やpermission overrideは行いません。
+
+checkpointは接続先の`fs/watch`で途中変更を観測し、入力hashも前後照合します。symlinkのcanonical targetが分からない場合、巨大な入力、読取/監視失敗は有効な検証にしません。全体の厳密固定が必要なら隔離した入力を使います。監督ID付きthread-shellは、準備後の送信直前に同じsession・connection・transportとactive状態を再確認し、受付応答までpause/stopと同じロックを保持します。先にpause/stopが完了すれば送信しません。送信中のpause/stopは`RECORD_BUSY`で失敗し、停止済みという誤った応答を返しません。受付応答後はロックを解放するためpause/stopできますが、すでに受け付けたコマンドの取消・終了は保証しません。応答不明でも自動再送せず、観測とleaseの扱いは上記に従います。
+
+## 公開検証情報
+
+回帰テストは架空の識別子・ホスト・一時プロファイルを使います。実アカウントの登録情報、接続先一覧、チャットやプロジェクトの実ID、業務タイトル、実行ログは公開しません。テスト件数、pause競合のローカル再現、依存DB照合の要約は`remote-cli-validation.json`を参照してください。
+
+`native`は観測専用、`control`は既存のactiveターンへの送信、`paired`は明示した管理操作を扱います。正式project IDとDesktop登録IDは別の識別子です。Desktopの承認・質問UIや表示は、RPC受付とは別に利用環境で確認してください。
+
+監督のpause/resume/stopでも、生成された`--host`と`--remote-transport`を保持してください。登録と異なるtransportの制御は`SUPERVISOR_MISMATCH`で拒否し、保存状態を変更しません。

package/docs/thread-create.md

@@ -1,12 +1,14 @@
 # Desktopプロジェクトにチャットを直接作成する
 
-`projects list`でローカルプロジェクトを確認し、`thread create`で初回指示付きのチャットを作成します。Desktopのnative RPCを使い、中継AIは実装から削除しました。「競馬」のような複数フォルダ・共有フォルダを持つプロジェクトにも対応します。
+本書のcaller不要standalone方式はローカル向けです。`--host ... --remote-transport paired thread create`のリモート作成・正式project ID・caller要件・host照合は[リモートCLI操作](remote-operations.md)を参照してください。
+
+`projects list`でローカルプロジェクトを確認し、`thread create`で初回指示付きのチャットを作成します。Desktopのnative RPCを使い、中継AIは実装から削除しました。「サンプル」のような複数フォルダ・共有フォルダを持つプロジェクトにも対応します。
 
 ```bash
 codexteer projects list --json
-codexteer thread create --project '競馬' \
+codexteer thread create --project 'サンプル' \
   --title '関連リポジトリの調査' '関連リポジトリを読み、結果を報告してください' --json
-codexteer thread create --project '競馬' \
+codexteer thread create --project 'サンプル' \
   --dry-run '調査してください' --json
 ```
 
@@ -29,11 +31,11 @@ terminal CLI → App Server thread/start（選択プロジェクトの全フォ
   → Desktopの所属サービスで登録・表示更新
 ```
 
-App Serverはnative操作用にcodexteer同梱の固定helperだけを起動します。native引数は所有者専用の一時JSONファイルで渡し、shellやargvへ埋め込みません。helperの許可操作はcatalog、list_projects、ローカルcreate_thread、新規チャット自身のmove_thread_to_projectだけです。新規チャットの初回処理以外のモデル推論は発生しません。
+App Serverはnative操作用にcodexteer同梱の固定helperだけを起動します。native引数は所有者専用の一時JSONファイルで渡し、shellやargvへ埋め込みません。helperの許可操作はcatalog、list_projects、固定上限のlist_threads、引数制限付きread_thread、ローカルcreate_thread、新規チャット自身のmove_thread_to_project、正確なthread IDだけを受け付けるnavigate_to_codex_pageです。navigate_to_codex_pageはpairedの購読確立のため制御側Desktopで対象リモートチャットを開きます。呼出し前に一覧とnative readでthread/hostを照合します。read_threadは[リモート観測](remote-observation.md)用で、作成先の範囲を広げません。新規チャットの初回処理以外のモデル推論は発生しません。
 
 作成前に、実行中サーバーと同じ同梱CLIからcommand/execとread-only sandboxのschemaを確認します。helperはDesktopのpeer認証を通過する署名付きApp Serverの正規の子として実行されます。Unix socketへ接続するためsandboxのnetworkAccessはtrueですが、helperにHTTP/DNSや外部サービスへの接続処理はありません。認証チェックや署名は変更しません。
 
-codexteerは選択プロジェクトからプライマリcwdと全workspace rootsを解決します。名前とcanonical所属をAPIで保存し、Desktopの購読を確立します。初回指示の前に範囲と空の履歴を確認します。初回受付後、Desktopのnative所属サービスを呼び、スケジュールと同じ所属ストアと表示へ反映します。作成応答だけを成功の証拠にせず、保存されたDesktop所属、canonical projectId、全フォルダ、userMessageとして保存された初回指示の完全一致とタイトルを照合します。関連付けを明示したnative作成の場合は、`codex_delegation`の呼出し元IDと本文を含むliteral全文を比較します。XMLとして解釈しません。
+codexteerは選択プロジェクトからプライマリcwdと全workspace rootsを解決します。名前とcanonical所属をAPIで保存し、Desktopの購読を確立します。初回指示の前に範囲と空の履歴を確認します。初回受付後、Desktopのnative所属サービスを呼び、スケジュールと同じ所属ストアと表示へ反映します。作成応答だけを成功の証拠にせず、Desktop native一覧のthread ID・local host・Desktop project ID、canonical projectId、全フォルダ、userMessageとして保存された初回指示の完全一致とタイトルを照合します。旧global stateファイルの`thread-project-assignments`だけを現在の所属とはみなしません。関連付けを明示したnative作成の場合は、`codex_delegation`の呼出し元IDと本文を含むliteral全文を比較します。XMLとして解釈しません。
 
 受付が履歴の永続化より早い場合は、最大5秒間、読取りだけで反映を待ちます。作成や初回ターンを再実行しません。standaloneではcanonical所属をthread/startで指定し、購読前にmetadata APIでも保存します。関連付けを明示したnative作成では必要に応じてmetadata APIでcanonical所属を登録します。Desktopの状態ファイル・DBを直接書き換えません。
 
@@ -45,11 +47,11 @@ CLI終了後の承認はDesktopが担当します。codexteerは承認を自動
 - standaloneで`--title`を省略すると、初回指示の空白をまとめた先頭80文字を名前にします。タイトル生成用のAIは起動しません。対象サーバーでは未使用の空チャットをDesktopが購読するために、先に名前を保存して履歴を永続化する必要があります。
 - cwd・permissions・sandbox・approval policy・approvals reviewerの上書きはnative schemaにないため、指定すると作成前に拒否します。
 - `--via-thread`のAI中継経路は削除しました。自動fallbackもありません。
-- 対応先は登録済みローカルプロジェクトです。worktree、remote、ChatGPT cloudは未対応です。
+- 本書のstandalone方式は登録済みローカルプロジェクト向けです。worktreeやクラウド実行はこの方式では扱いません。Codex Cloudには`--connection cloud thread create --project <ENV_ID>`で同じ作成操作を使えます。環境一覧・監督を含む[Cloud操作](cloud.md)を参照してください。
 - `--timeout-ms`は各RPCの待機期限で、既定120000、1000〜600000です。
 - `--dry-run`は接続・プロジェクト・native schemaを読み、チャット・指示・receiptを作りません。
 
-native RPCはDesktop内部のversion依存APIです。この実装の実測はDesktop `26.1007.30912`と`26.1007.71326` / 同梱CLI `0.162.0-alpha.17.2`です。未対応schema、unsafe socket、変更されたendpoint、認証拒否では止めます。
+native RPCはDesktopのバージョンに依存します。未対応schema、unsafe socket、変更されたendpoint、認証拒否では止めます。
 
 wrapperはnative endpointを所有者専用runtimeに公開します。公開されていない旧wrapperでは、選択済み・所有者検証済みPIDと同梱Node実行ファイルを確認し、継承環境のnative endpointだけを取得します。環境全体を出力・保存しません。
 
@@ -67,49 +69,22 @@ wrapperはnative endpointを所有者専用runtimeに公開します。公開さ
 - `verification_status: verified`と所属・初回指示の個別verifiedが、照合完了の証拠です。
 - 最終receipt保存だけ失敗した場合は`receipt_update_required`を返します。受付済み操作を再送可能な失敗に変換しません。
 
-## 実機検証 (2026-10-14 JST)
-
-- 直接作成と承認: `01a135f5-85aa-7410-a0cf-1a0eed53037f`、attempt `b7479787-a995-4566-a1d0-5f05a8bc6035`。native CLIは終了済みでもDesktopで`waitingOnApproval`が継続。Desktop一覧のprojectIdは「競馬」の`ad16728e-81d9-499f-81c8-fdf13f0f9d89`。初回commentaryに`CODEXTEER_NATIVE_INITIAL_INSTRUCTION_OK`。
-- ユーザーの「今回だけ承認」後、`printf CODEXTEER_NATIVE_APPROVAL_OK`がexit 0、最終応答`CODEXTEER_NATIVE_APPROVAL_ROUNDTRIP_OK`を確認。
-- この最初の試行は受付直後の履歴照合が早すぎ、CLIがcreated/acceptedの部分成功を返した。反映待ちを修正し、同じ子ID・同じattemptを読み取り照合してreceiptを確定。再作成・再送していない。
-- 修正後CLI全体: `01a135f9-3974-7983-a756-5d6b31968fd0`、attempt `daf87c13-7df3-45b0-acb6-4e7ea56f32ef`。Desktop所属・canonical所属・7フォルダ・初回指示・タイトルの照合を完了しexit 0。最終応答`CODEXTEER_NATIVE_CREATE_VERIFIED`。
-- contextは`01a135b4-b84b-7530-9c25-5bde83077c9e`の既存completedターン。終了後もidle、turn数1、latest turnは`01a135b4-bac5-7f62-9014-d109c5a37b92`。中継AIターンは発生していない。
-- 稼働中wrapperを中断しないため、実Desktopの作成試験は同梱NodeでCLIを直接実行した。当時のcontrol経路はローカルsocket試験までで、その後の実機確認で修正しました。現行経路と結果は次節を参照。
-
-これらは特定Desktop/CLIの実測で、将来のリリースや全承認種別の認定ではありません。[調査時の経路とコード根拠](thread-create-native-investigation.md)も参照してください。
-
-## 再起動後の通常CLI検証 (2026-10-15 JST)
-
-Desktop `26.1007.71326` / 同梱CLI `0.162.0-alpha.17.2`で実測しました。
+## 作成済みreceiptの再照合
 
-- 最初の再起動後、旧native_tools_rpc:1のwrapper自身の接続は`missing-code-signing-identity`で拒否され、dry-runで停止。チャットは作成していません。
-- 接続元の起動経路を修正し、既存App Serverのcommand/execから固定の署名付きhelperをread-only sandboxで起動する方式に切り替えました。追加の再起動なしで通常CLIのdry-runが成功しました。
-- 通常の`codexteer thread create --project 競馬 --context-thread ...`がexit 0。作成IDは`01a13e01-2d5a-7bc2-a752-dbdddda9d1ea`、attemptは`68b4064b-eabc-444b-8607-935e66ebbb62`です。Desktop一覧の「競馬」所属、canonical所属、7フォルダ、タイトル、初回指示を全てverifiedで返しました。
-- 初回commentaryに`CODEXTEER_STANDARD_CLI_INITIAL_OK`、printfがexit 0、最終応答`CODEXTEER_STANDARD_CLI_ROUNDTRIP_OK`。この時のDesktop設定はauto_reviewでした。
-- 手動承認は同じ検証チャットだけをapprovalsReviewer:user / on-request / read-onlyへ変更した後続ターン`01a13e03-559a-7f12-9d9f-2d7650c52ae8`で確認しました。他チャットやプロジェクト設定は変更していません。
-- このターンの短命senderは`2026-10-15T05:22:48.359Z`に終了し、その後もDesktopのwaitingOnApprovalが継続。ユーザーの「今回だけ承認」後、`printf CODEXTEER_STANDARD_CLI_HUMAN_APPROVAL_OK`がexit 0、最終応答`CODEXTEER_STANDARD_CLI_HUMAN_ROUNDTRIP_OK`を確認しました。
-- 呼出し元`01a135b4-b84b-7530-9c25-5bde83077c9e`は元のcompletedターン1件のままです。中継AIや追加ターンは発生していません。
-
-## 回帰・配布検証
-
-native直接作成の時点では`npm run check`成功、`node --test --test-concurrency=1`は320件中318成功・2skip・失敗0。配布テストもPASSで、76ファイルのpack、publish dry-run、offline install、npm/npx起動を確認しました。公開は行っていません。
+```bash
+codexteer thread verify <ATTEMPT-ID> --json
+```
 
-並列実行では既存checkpointのファイル監視テストが一度失敗しました。同テストの単独実行と全体の逐次実行は成功しています。今回のnative helper関連テストは全て成功しています。
+`creation_status: created`、`sent: true`、`delivery_status: accepted`を持つschema 2/3のreceiptを、同じCODEX_HOMEで再照合します。作成・購読・移動・metadata更新・指示送信は行いません。新しいthread/turnやAI処理も発生しません。更新するのはcodexteer自身のreceiptだけで、以前の照合状態・エラーと今回の全チェックを`verification_history`へ残します。unknown/dispatching/未受付をこのコマンドで成功扱いにはしません。
 
-## 呼出し元なし・最小引数での検証 (2026-10-15 JST)
+Desktop native所属、現在のプロジェクトID対応と全フォルダ、threadのcanonical所属・cwd・全フォルダ・指定タイトルに加え、保存された初回本文のSHA-256とUnicode文字数をreceiptと比較します。standaloneでは初回turn IDも一致が必要です。初回本文を再度渡す必要はありません。関連付けを明示した場合は既知の呼出し元を含むliteral envelopeから本文を取り出し、XMLとして解釈しません。
 
-`env -u CODEX_THREAD_ID codexteer thread create --project 競馬 '初回指示' --json`で実測しました。`--context-thread`、`--title`、モデル・権限上書きは指定していません。
+native一覧はDesktopの実schemaに従い最新50件と全pinnedです。対象が見つからない、別host/projectに所属する、重複して見える、schemaやruntimeが変わる場合は成功と推測しません。失敗の`verification_checks`を確認してください。`--timeout-ms`は各RPCの期限です。`--supervisor`と観測専用の`--connection desktop`からは実行できません。保存済みCLIは変更しないため、この機能には修正版CLIが必要です。
 
-- 最終CLIはexit 0。threadは`01a13e22-e9db-71a3-b0d2-703586bf84d5`、attemptは`ed2dc9ec-ac30-445c-9586-dbfcd336179e`。Desktopの「競馬」所属、canonical所属、全7フォルダ、初回指示と名前がverifiedです。
-- `context_thread_id` / `context_turn_id`はnull。native所属登録のcontextは新規thread自身と、その実際の初回ターン`01a13e22-ebfa-7541-b7a1-789676672435`です。既存チャットの読取りやAIターンは不要です。
-- 初回ターンはcompleted、最終応答`CODEXTEER_PROJECT_PROMPT_ONLY_FINAL_OK`。初回指示は通常のuserMessageとして完全一致し、作成時に開始したターンはこの1件だけです。
-- タイトル未指定の試験で、初回ターン前の未保存チャットはDesktop購読やmetadata保存を拒否される条件が見つかりました。名前を先にAPIで保存し、canonical所属を保存してから購読するよう修正しました。途中の2試行はcreated/not_sentのreceiptを保持しています。`95bdf33c-7580-40da-90e2-a2882f4b83af`は履歴0件を確認してアーカイブしました。`cf88c307-7e8d-4140-a074-ed25fa551916`は作成後の読取りをAPIが拒否したため状態を断定せず、receiptを保持しています。いずれも初回指示の送信前で停止し、再送していません。
-- 承認試験は同じ最終チャットの後続ターン`01a13e23-e670-7e60-8107-5317fbbca458`のみをuser/on-request/read-onlyにして実施。作成時のDesktop購読を再利用し、新たな購読は行っていません。短命senderは`2026-10-15T05:58:22.584Z`に終了し、その後もDesktopでwaitingOnApprovalが継続しました。ユーザーの「今回だけ承認」後、`printf CODEXTEER_STANDALONE_HUMAN_APPROVAL_OK`がexit 0、最終応答`CODEXTEER_STANDALONE_HUMAN_ROUNDTRIP_OK`、ターンcompletedを確認しました。所属・7フォルダ・初回指示も再照合し、同じattemptのreceiptをhuman_approval_roundtrip:verifiedへ更新しました。
-- 全体の逐次テストは327件中325成功・2skip・失敗0、`npm run check`と`git diff --check`も成功しました。sandbox内のNode 25によるUnix socket試験は実行環境のassertで終了したため、ローカルsocketを許可した環境で実行・確認しました。
-- 更新後の配布テストもPASS。77ファイルのpack、publish dry-run、offline install、npm exec/npx、保存CLIと混在バージョンの回帰を確認しました。公開は行っていません。
+## 検証と互換性
 
-## PRレビューでの修正 (0.17.0公開候補)
+作成とreceipt照合の回帰テストは、架空のプロジェクト・識別子・一時プロファイルを使います。未知の応答、別プロジェクト、追加root、初回指示の不一致では停止し、作成や配送を繰り返しません。実環境で使う前に、その環境のDesktopとCLIでschema・所属・購読・承認動作を確認してください。
 
-内部RPCエラーを実際の`RpcFailure`型で模擬すると、処理が実行された可能性があっても`not_created` / `not_sent`になる問題が再現しました。内部エラー（`-32603`など）は`unknown`を保持し、メソッド・引数エラー（`-32601` / `-32602`）だけを実行前の拒否として扱うよう修正しています。standaloneの作成・初回配送、native helperと明示的context作成の回帰テストを追加しました。未確認の操作を自動再実行する処理は追加していません。
+この文書のプロジェクト名とIDは説明用の例です。実際のチャットID、プロジェクト一覧、ローカルパス、実行ログは公開資料に含めません。
 
-公開前の全回帰で、既存のcheckpoint試験がmacOSの監視通知の到着順に依存して失敗することを変更前のmainでも確認しました。edit-and-restore試験は監視イベントまたはスナップショットのメタデータ差分で対象ファイルの変更が検出されたことを確認し、無効化されるという契約を維持しています。checkpointの実装は変更していません。
+DesktopのCloud環境構成で作成する場合は[Desktop Cloud](desktop-cloud.md)を参照してください。環境選択とローカルDesktopプロジェクト所属は別で、通常のリモートCloud環境への初回所属登録は未対応です。Desktop自身の実行環境に限定した署名付きAPIの対応範囲は、Desktop Cloudの説明を参照してください。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexteer",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Send steering messages to running Codex Desktop threads from a terminal.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "check": "node scripts/check-syntax.mjs",
     "test": "node --test",
     "test:protocol": "node scripts/probe-app-server.mjs",
+    "test:remote-control": "node scripts/probe-remote-control.mjs",
     "test:connection": "node scripts/probe-desktop-connection.mjs",
     "benchmark:read": "node scripts/benchmark-read.mjs",
     "test:package": "node scripts/test-package.mjs"
@@ -26,14 +27,22 @@
     "url": "git+https://github.com/vinhphatfsg/codexteer.git"
   },
   "files": [
+    "docs/cloud.md",
+    "docs/desktop-cloud.md",
     "bin/*.mjs",
     "src/*.mjs",
     "scripts/*.applescript",
     "assets/send-pururu.wav",
+    "assets/remote-device-key.swift",
     "CHANGELOG.md",
     "docs/distribution.md",
+    "docs/orchestration.md",
     "docs/thread-create.md",
-    "docs/thread-create-native-investigation.md"
+    "docs/remote-observation.md",
+    "docs/remote-control.md",
+    "docs/remote-device-enrollment.md",
+    "docs/remote-operations.md",
+    "docs/remote-cli-validation.json"
   ],
   "bundleDependencies": [
     "ws"

package/scripts/update-desktop.applescript

@@ -0,0 +1,51 @@
+-- Match known update labels inside the fixed Codex application process.
+-- This does not authenticate a Sparkle window. Nonmatching controls and OS
+-- permission prompts are left to the user.
+on run argv
+  set operation to item 1 of argv
+  tell application "System Events"
+    if not (exists (first application process whose bundle identifier is "com.openai.codex")) then return "absent"
+    set appProcess to first application process whose bundle identifier is "com.openai.codex"
+    tell appProcess
+      if operation is "preflight" or operation is "check" then
+        repeat with entry in menu items of menu 1 of menu bar item 2 of menu bar 1
+          if name of entry is in {"Check for Updates…", "Check for Updates...", "更新を確認…", "更新を確認..."} then
+            if not enabled of entry then error "The update menu is disabled."
+            if operation is "check" then click entry
+            return "checking"
+          end if
+        end repeat
+        error "Supported Codex update menu not found (English/Japanese supported)."
+      end if
+      if operation is not "advance" and operation is not "inspect" then error "Unknown updater operation."
+      -- Do not retain System Events' name-based window references: multiple
+      -- Codex windows may have the same title. Resolve positional references
+      -- afresh, and tolerate only stale AX elements during this polling pass.
+      repeat with windowIndex from 1 to count of windows
+        try
+          repeat with buttonIndex from 1 to count of buttons of window windowIndex
+            try
+              set buttonName to name of button buttonIndex of window windowIndex
+              if buttonName is in {"Install and Relaunch", "インストールして再起動", "Install Update", "アップデートをインストール"} then
+                if enabled of button buttonIndex of window windowIndex then
+                  if operation is "advance" then click button buttonIndex of window windowIndex
+                  if buttonName is in {"Install and Relaunch", "インストールして再起動"} then return "installing"
+                  return "downloading"
+                end if
+              end if
+            on error errorMessage number errorNumber
+              if errorNumber is not -1719 and errorNumber is not -1728 then error errorMessage number errorNumber
+            end try
+          end repeat
+          repeat with textIndex from 1 to count of static texts of window windowIndex
+            set messageText to value of static text textIndex of window windowIndex as text
+            if messageText contains "You’re up to date!" or messageText contains "currently the newest version available" or messageText contains "最新版を使用しています!" or messageText contains "は現在入手できる最新バージョンです" then return "up_to_date"
+          end repeat
+        on error errorMessage number errorNumber
+          if errorNumber is not -1719 and errorNumber is not -1728 then error errorMessage number errorNumber
+        end try
+      end repeat
+    end tell
+  end tell
+  return "waiting"
+end run

package/src/agent-launch.mjs

@@ -0,0 +1,27 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { constants } from "node:os";
+
+function launchFailure(agent, error) {
+  return Object.assign(new Error(`Could not start ${agent} (${error.code ?? "START_FAILED"}). Check that it is installed and executable on PATH.`), { code: error.code ?? "START_FAILED" });
+}
+
+export async function launchAgent(agent, agentArgs, prompt) {
+  let child;
+  try {
+    // Keep forwarded argv intact. The agent's own terminator keeps its variadic
+    // options from consuming the generated prompt as another option value.
+    child = spawn(agent, [...agentArgs, "--", prompt], { shell: false, stdio: "inherit" });
+  } catch (error) { throw launchFailure(agent, error); }
+
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const handlers = signals.map(signal => () => {
+    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  });
+  signals.forEach((signal, index) => process.on(signal, handlers[index]));
+  try {
+    const [code, signal] = await once(child, "exit");
+    return code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1);
+  } catch (error) { throw launchFailure(agent, error); }
+  finally { signals.forEach((signal, index) => process.off(signal, handlers[index])); }
+}

package/src/app-server.mjs

@@ -1,3 +1,5 @@
+import { isDesktopCloudTask } from "./desktop-cloud-id.mjs";
+import { sendDesktopCloudInput } from "./desktop-cloud.mjs";
 import { mkdir, rm, readFile, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
@@ -7,9 +9,14 @@ import { normalizeThreadId } from "./thread-id.mjs";
 import { ensureDesktopSubscription } from "./subscription.mjs";
 import { assertRuntimeOperation, compatibleClient } from "./compatibility.mjs";
 import { turnMetadata } from "./paged-read.mjs";
+import { targetHost, remoteReadOnly, remoteTransport, hostNamespace, hostFields, isControlTransport } from "./target.mjs";
+import { remoteControlConnection, remoteNewTurnUnsupported } from "./remote-control.mjs";
+import { ensureRemoteDesktopSubscription } from "./remote-management.mjs";
+import { isCloudTask } from "./task-id.mjs";
+import { sendCloudInput } from "./cloud-send.mjs";
 
 export class SendFailure extends Error {
-  constructor(message, { code = "NOT_SENT", uncertain = false, threadId, rpcCode, capability, operation } = {}) {
+  constructor(message, { code = "NOT_SENT", uncertain = false, threadId, rpcCode, capability, operation, remoteControlAuth } = {}) {
     super(message);
     this.code = code;
     this.delivery_status = uncertain ? "unknown" : "not_sent";
@@ -18,12 +25,22 @@ export class SendFailure extends Error {
     this.rpc_code = rpcCode;
     this.capability = capability;
     this.operation = operation;
+    this.remote_control_auth = remoteControlAuth;
   }
 }
 
 function activeTurn(thread) {
+  if (thread.status?.type !== "active") return null;
+  if (thread.historyMode === "paginated") {
+    // readSendState obtains every page in ascending order. Codex may also
+    // report orphaned historical turns as inProgress while a new turn runs.
+    // The latest turn is only a candidate: turn/steer.expectedTurnId must
+    // still match the actual runtime turn. Never fall back to an older ID.
+    const latest = thread.turns?.at(-1);
+    return latest?.status === "inProgress" ? latest : null;
+  }
   const turns = thread.turns?.filter(turn => turn.status === "inProgress") ?? [];
-  return thread.status?.type === "active" && turns.length === 1 ? turns[0] : null;
+  return turns.length === 1 ? turns[0] : null;
 }
 
 function verifyThread(thread, threadId) {
@@ -57,7 +74,7 @@ export async function sendOnClient(client, threadId, message, { newTurn = false,
   const input = [{ type: "text", text: message }];
   if (!newTurn) {
     const turn = activeTurn(thread);
-    if (!turn) throw new Error("The task has no unambiguous active turn. Use --new-turn for an idle task.");
+    if (!turn) throw new Error("The task has no eligible active turn. Read it again before sending; use --new-turn only for an idle task.");
     await beforeSend?.(thread, client);
     // Desktop uses clientId on the resulting userMessage to render external
     // steering as a user bubble instead of just an anonymous "steered" marker.
@@ -84,10 +101,17 @@ export async function sendOnClient(client, threadId, message, { newTurn = false,
   return { turn_id: accepted.turn.id, client_message_id: clientUserMessageId };
 }
 
-export async function sendAppServerMessage(threadInput, message, { dryRun = false, newTurn = false, clientMessageId = randomUUID(), beforeSend, connect = RpcClient.connect, discover = discoverRuntime, subscribe = ensureDesktopSubscription, inspectControl = verifyControlEndpoint } = {}) {
+export async function sendAppServerMessage(threadInput, message, { dryRun = false, newTurn = false, clientMessageId = randomUUID(), beforeSend, connect, discover, subscribe = ensureDesktopSubscription, inspectControl = verifyControlEndpoint } = {}) {
+  if (isDesktopCloudTask(threadInput)) return sendDesktopCloudInput(threadInput, message, { dryRun, newTurn, clientMessageId, beforeSend });
+  if (isCloudTask(threadInput)) return sendCloudInput(threadInput, message, { dryRun, newTurn, clientMessageId, beforeSend });
+  const remote = targetHost() !== "local";
+  if (remote && !isControlTransport()) throw remoteReadOnly();
+  if (remote && newTurn && remoteTransport() !== "paired") throw remoteNewTurnUnsupported();
+  const route = remote ? remoteControlConnection() : {};
+  connect ??= route.connect ?? RpcClient.connect; discover ??= route.discover ?? discoverRuntime;
   const threadId = normalizeThreadId(threadInput);
   if (typeof message !== "string" || !message.trim()) throw new Error("Message must not be empty.");
-  const plan = { thread_id: threadId, backend: "app-server", delivery_action: newTurn ? "new-turn" : "steer", message_characters: [...message].length, dry_run: dryRun };
+  const plan = { thread_id: threadId, ...hostFields(), backend: "app-server", delivery_action: newTurn ? "new-turn" : "steer", message_characters: [...message].length, dry_run: dryRun };
   if (dryRun) return { ...plan, sent: false, delivery_status: "not_sent" };
   let client;
   let lock;
@@ -97,8 +121,8 @@ export async function sendAppServerMessage(threadInput, message, { dryRun = fals
   try {
     const { paths, state } = await discover();
     assertRuntimeOperation(state, operation);
-    if (newTurn) await inspectControl(paths);
-    const candidate = path.join(paths.lease, `send-${threadId}`);
+    if (newTurn && !remote) await inspectControl(paths);
+    const candidate = path.join(paths.lease, `send-${remote ? `${hostNamespace()}-` : ""}${threadId}`);
     try { await mkdir(candidate, { mode: 0o700 }); } catch (error) {
       if (error.code === "EEXIST") throw new Error("Another send is in progress for this task, or a previous sender exited unexpectedly. Restart the shared Desktop after checking delivery before retrying.");
       throw error;
@@ -111,18 +135,18 @@ export async function sendAppServerMessage(threadInput, message, { dryRun = fals
       if (current.state.instance !== state.instance || current.paths.socket !== paths.socket || (newTurn && current.paths.control !== paths.control)) {
         throw Object.assign(new Error("Runtime changed before delivery. Read the target again before sending."), { code: "RUNTIME_CHANGED" });
       }
-      if (newTurn) await inspectControl(current.paths);
+      if (newTurn && !remote) await inspectControl(current.paths);
     };
     const receipt = await sendOnClient(client, threadId, message, { newTurn, clientMessageId,
       beforeSend: async (...args) => { await beforeSend?.(...args); await checkRuntime(); },
-      subscribe: async id => { await checkRuntime(); return subscribe(paths.control, id); },
+      subscribe: async id => { await checkRuntime(); return remote ? ensureRemoteDesktopSubscription(id) : subscribe(paths.control, id); },
     });
     result = { ...plan, ...receipt, sent: true, delivery_status: "accepted" };
     return result;
   } catch (error) {
     throw new SendFailure(error.uncertain
       ? "Delivery is unknown because App Server did not confirm receipt. Check the target task before retrying."
-      : error.message, { code: error.code ?? "NOT_SENT", uncertain: error.uncertain, threadId, rpcCode: error.rpcCode, capability: error.capability, operation: error.operation });
+      : error.message, { code: error.code ?? "NOT_SENT", uncertain: error.uncertain, threadId, rpcCode: error.rpcCode, capability: error.capability, operation: error.operation, remoteControlAuth: error.remote_control_auth });
   } finally {
     // Cleanup failure must never turn an acknowledged send into a retryable
     // error. Keep its acceptance receipt and leave any stale lock fail-closed.

package/src/checkpoint.mjs

@@ -4,14 +4,17 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { fingerprintFile, collectEvidence, verifyEvidence } from "./evidence.mjs";
 import { digest } from "./observe.mjs";
-import { normalizeThreadId } from "./thread-id.mjs";
+import { normalizeTaskId } from "./task-id.mjs";
 import { readRecord, writeRecord, listRecords, withStoreLock } from "./store.mjs";
 import { runCommand } from "./runner.mjs";
+import { targetHost } from "./target.mjs";
+import { remoteCaptureInputs, remoteCheckpointScope, remoteWatchInputs } from "./remote-io.mjs";
 
 const within = (file, root) => file === root || file.startsWith(root + path.sep);
 function excluded(file, excludes) { return file.split(path.sep).includes(".git") || excludes.some(x => within(file, x)); }
 
 export async function captureInputs(roots, excludes = [], { allowMissing = false } = {}) {
+  if (targetHost() !== "local") return remoteCaptureInputs(roots, excludes, { allowMissing });
   const records = new Map();
   async function visit(file) {
     if (excluded(file, excludes) || records.has(file)) return;
@@ -38,18 +41,20 @@ function differences(before, after) {
 }
 
 export async function getCheckpoint(threadInput, id, storage = {}) {
-  const threadId = normalizeThreadId(threadInput), entry = await readRecord("checkpoints", id, storage);
+  const threadId = normalizeTaskId(threadInput), entry = await readRecord("checkpoints", id, storage);
   if (!entry || entry.thread_id !== threadId || entry.id !== id) throw new Error("Checkpoint not found for this task.");
   return entry;
 }
 
 export async function createCheckpoint(threadInput, name, { paths, excludes = [], cwd = process.cwd(), ...storage }) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   if (!name?.trim() || !paths?.length) throw new Error("capture requires a name and at least one --path.");
-  const roots = [...new Set(paths.map(p => path.resolve(cwd, p)))], omit = excludes.map(p => path.resolve(cwd, p));
+  const scope = targetHost() === "local" ? { cwd: path.resolve(cwd), roots: [...new Set(paths.map(p => path.resolve(cwd, p)))], excludes: excludes.map(p => path.resolve(cwd, p)) }
+    : await remoteCheckpointScope(threadId, paths, excludes);
+  const { roots, excludes: omit } = scope;
   const snapshot = await captureInputs(roots, omit);
   if (!snapshot.files.some(f => f.type === "file")) throw new Error("No input files were selected.");
-  const entry = { schema: 1, id: randomUUID(), thread_id: threadId, name, cwd: path.resolve(cwd), created_at: new Date().toISOString(), snapshot, runs: [], artifacts: [] };
+  const entry = { schema: 1, id: randomUUID(), thread_id: threadId, name, cwd: scope.cwd, created_at: new Date().toISOString(), snapshot, runs: [], artifacts: [] };
   await writeRecord("checkpoints", entry.id, entry, storage);
   return checkpointSummary(entry);
 }
@@ -72,39 +77,70 @@ export async function verifyCheckpoint(threadInput, id, storage = {}) {
 }
 
 function watchInputs(snapshot) {
-  const touched = new Set(), watchers = []; let error = null;
+  const touched = new Set(), watchers = []; let error = null, pending = Promise.resolve(), dirty = false, scanning = false;
+  // macOS can deliver queued events for files created before watch startup,
+  // including parent notifications for excluded outputs. Confirm an event
+  // against the input snapshot rather than treating its path alone as a write.
+  const scan = () => {
+    dirty = true;
+    if (scanning) return;
+    scanning = true;
+    pending = pending.then(async () => {
+      while (dirty) {
+        dirty = false;
+        try {
+          const current = await captureInputs(snapshot.roots, snapshot.excludes, { allowMissing: true }), changes = differences(snapshot, current);
+          for (const file of [...changes.added, ...changes.removed, ...changes.changed]) if (touched.size < 100) touched.add(file);
+        } catch (e) { error = e.message; }
+      }
+    }).finally(() => { scanning = false; });
+  };
   const files = new Map(snapshot.files.map(f => [f.ref, f]));
   const dirs = [...new Set(snapshot.roots.map(r => files.get(r)?.type === "directory" ? r : path.dirname(r)))];
   try {
     for (const dir of dirs) {
-      const watcher = watch(dir, { recursive: true }, (_, filename) => {
+      const watcher = watch(dir, { recursive: true }, (eventType, filename) => {
         const file = filename ? path.resolve(dir, filename.toString()) : dir;
-        if (!excluded(file, snapshot.excludes) && (!filename || snapshot.roots.some(r => within(file, r)))) { if (touched.size < 100) touched.add(file); }
+        if (!excluded(file, snapshot.excludes) && (!filename || snapshot.roots.some(r => within(file, r)))) {
+          // A content-change event on an existing input remains evidence even
+          // if it was restored within the filesystem timestamp resolution.
+          if (eventType === "change" && files.get(file)?.type === "file" && touched.size < 100) touched.add(file);
+          scan();
+        }
       });
       watcher.on("error", e => { error = e.message; }); watchers.push(watcher);
     }
   } catch (e) { for (const w of watchers) w.close(); throw e; }
-  return { touched, get error() { return error; }, close() { for (const w of watchers) w.close(); } };
+  return { touched, get error() { return error; }, settle: () => pending, async close() { for (const w of watchers) w.close(); await pending; } };
 }
 
-export async function runCheckpoint(threadInput, id, argv, { timeoutMs = 0, ...storage } = {}) {
+export async function runCheckpoint(threadInput, id, argv, { timeoutMs = 0, execBackend, remoteShell, supervisor, connection, ...storage } = {}) {
   if (!argv.length || !argv[0] || !Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 86400000) throw new Error("A command and timeout-ms between 0 and 86400000 are required.");
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   return withStoreLock(`checkpoint-${id}`, async () => {
-    const entry = await getCheckpoint(threadId, id, storage), watcher = watchInputs(entry.snapshot);
+    const entry = await getCheckpoint(threadId, id, storage), watcher = targetHost() === "local" ? watchInputs(entry.snapshot) : await remoteWatchInputs(entry.snapshot);
     try {
       const before = await captureInputs(entry.snapshot.roots, entry.snapshot.excludes, { allowMissing: true });
       if (before.digest !== entry.snapshot.digest) throw new Error("Inputs changed since capture. Capture a new checkpoint before running.");
       const run = { id: randomUUID(), argv, status: "running", started_at: new Date().toISOString() };
       entry.runs.push(run); await writeRecord("checkpoints", id, entry, storage);
-      const result = await runCommand(argv, { cwd: entry.cwd, timeoutMs, onStart: async pid => { run.pid = pid; await writeRecord("checkpoints", id, entry, storage); } });
+      let result;
+      try { result = await runCommand(argv, { cwd: entry.cwd, timeoutMs, execBackend, remoteShell, supervisor, connection, threadId, onStart: async (pid, info) => { Object.assign(run, { pid }, info); await writeRecord("checkpoints", id, entry, storage); } }); }
+      catch (error) {
+        Object.assign(run, { status: error.uncertain ? "unknown" : "failed", error_code: error.code, error: error.message, inputs_unchanged: false,
+          remote_process_id: error.remote_process_id, touched_paths: [...watcher.touched], observation_error: watcher.error, completed_at: new Date().toISOString() });
+        await writeRecord("checkpoints", id, entry, storage); throw error;
+      }
       let after, snapshotError;
       try { after = await captureInputs(entry.snapshot.roots, entry.snapshot.excludes, { allowMissing: true }); } catch (e) { snapshotError = e.message; }
+      await watcher.settle?.();
+      const changedInputs = after ? differences(entry.snapshot, after) : null;
+      const touchedPaths = [...new Set([...watcher.touched, ...(changedInputs ? [...changedInputs.added, ...changedInputs.removed, ...changedInputs.changed] : [])])].slice(0, 100);
       Object.assign(run, result, { status: "completed", inputs_unchanged: after?.digest === entry.snapshot.digest && !watcher.touched.size && !watcher.error,
-        touched_paths: [...watcher.touched], observation_error: watcher.error ?? snapshotError ?? null, differences: after ? differences(entry.snapshot, after) : null });
+        touched_paths: touchedPaths, observed_touched_paths: [...watcher.touched], observation_error: watcher.error ?? snapshotError ?? null, differences: changedInputs });
       await writeRecord("checkpoints", id, entry, storage);
       return { checkpoint_id: id, ...run, valid: run.exit_code === 0 && !run.error && !run.timed_out && run.inputs_unchanged };
-    } finally { watcher.close(); }
+    } finally { await watcher.close(); }
   }, storage);
 }
 
@@ -123,6 +159,6 @@ export async function attachArtifacts(threadInput, id, refs, storage = {}) {
 }
 
 export async function listCheckpoints(threadInput, storage = {}) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   return (await listRecords("checkpoints", storage)).filter(c => c?.thread_id === threadId).sort((a, b) => a.created_at.localeCompare(b.created_at)).map(entry => checkpointSummary(entry));
 }