codexteer 0.17.0 → 0.18.0

package/docs/distribution.md

@@ -1,11 +1,11 @@
 # 配布と永続実行
 
 パッケージ名は `codexteer`、CLI名は `codexteer`、ライセンスはMITです。
-旧npmパッケージは`@vinhphatfsg/codex-steer`です。`codexteer@0.16.0`は公開済みで、このブランチはプロジェクトチャット作成を追加するマイナー更新`0.17.0`を準備します。GitHubのPR作成・マージはnpm公開を行う操作ではありません。公開時は`npm whoami`でnpm側のユーザーを確認してください。
+旧npmパッケージは`@vinhphatfsg/codex-steer`です。`codexteer@0.17.0`は公開済みで、このブランチはリモート操作・Cloud対応などをまとめたマイナー更新`0.18.0`を準備します。GitHubのPR作成・マージはnpm公開を行う操作ではありません。公開時は`npm whoami`でnpm側のユーザーを確認してください。
 `package.json` は `private` を持たず、`publishConfig` でnpm公式レジストリへのpublic公開を指定しています。公開可能な設定であることと、実際に公開済みであることは別です。
 
 公開後の基本的な実行形式は次のとおりです。通常はバージョン指定なしで使えます。監督開始後は保存したCLIを使い続けるため、監督中の一貫性を保つために版を明示する必要はありません。起動側と操作側の製品バージョンも、必要な通信仕様が対応していれば異なっていても使えます。
-以下の監督機能は公開済みの0.15.0から利用できます。0.16.0では通知集約と監督プロンプトを改善しました。0.17.0のチャット作成機能は公開準備中のため、公開前はこのブランチをソースから導入してください。`-y` はnpmの取得確認を省略します。
+以下の監督機能は公開済みの0.15.0から利用できます。0.16.0では通知集約と監督プロンプトを改善しました。0.18.0のチャット作成機能は公開準備中のため、公開前はこのブランチをソースから導入してください。`-y` はnpmの取得確認を省略します。
 
 ```text
 npx -y codexteer desktop start
@@ -179,7 +179,7 @@ npxから模擬Claudeと模擬Codexを起動して保存したCLIへの参照を
 
 レビュー・検証を終えた版を、npm側の公開権限を持つアカウントで公開します。手動公開には2FAを有効にしたアカウントを使ってください。
 
-公開済みのパッケージ名とバージョンの組み合わせは再公開できません。既存の`codexteer@0.16.0`は変更せず、今回の配布物は`codexteer@0.17.0`として準備します。公開は別途実行します。削除しても同じ名前・版番号の組み合わせを再利用できません。[npm publishの仕様](https://docs.npmjs.com/cli/v11/commands/npm-publish/)
+公開済みのパッケージ名とバージョンの組み合わせは再公開できません。既存の`codexteer@0.17.0`は変更せず、今回の配布物は`codexteer@0.18.0`として準備します。公開は別途実行します。削除しても同じ名前・版番号の組み合わせを再利用できません。[npm publishの仕様](https://docs.npmjs.com/cli/v11/commands/npm-publish/)
 
 ```bash
 npm login
@@ -188,11 +188,11 @@ npm run test:package
 npm publish --access public
 ```
 
-公開後は、公開した版と起動コマンドの登録を確認します。次は0.17.0を公開した場合の例です。
+公開後は、公開した版と起動コマンドの登録を確認します。次は0.18.0を公開した場合の例です。
 
 ```bash
-npm view codexteer@0.17.0 version bin --json
-npx -y codexteer@0.17.0 --version
+npm view codexteer@0.18.0 version bin --json
+npx -y codexteer@0.18.0 --version
 ```
 
 `EPRIVATE`はリポジトリの`package.json`に公開禁止設定が残っていることを示します。`--access public`はその禁止を解除しません。
@@ -204,9 +204,9 @@ npx -y codexteer@0.17.0 --version
 
 ここからの監督制御、指摘管理、Codex CLI起動、接続方式の選択は0.15.0で追加しました。保存済みCLIの機能自体は0.14.1から利用できます。0.16.0は通知集約と監督プロンプトの改善を含むminor更新です。`watch --stream`の既定はdigestで、`--notify all`を明示すると従来の即時出力になります。単発watchと保存済みCLIの動作は変わりません。runtime protocolと既存capabilityのv1契約は維持し、0.15.0で起動したDesktopとの通信に再起動は不要です。
 
-保存したCLIへのコマンドは、canonical CODEX_HOME、Node guard、`--supervisor <session-id>`、`--connection shared|desktop`を一緒に保持します。各プロンプト生成は新しいIDを発行しますが、生成だけでは登録しません。直接起動はエージェント起動前に登録し、終了時に停止します。コピーした本文は最初のregisterで開始します。
+保存したCLIへのコマンドは、canonical CODEX_HOME、Node guard、`--supervisor <session-id>`、`--connection shared|desktop|cloud|desktop-cloud`を一緒に保持します。各プロンプト生成は新しいIDを発行しますが、生成だけでは登録しません。直接起動はエージェント起動前に登録し、終了時に停止します。コピーした本文は最初のregisterで開始します。
 
-同じホームの`codex-steer/supervisors`はタスク別の制御、`supervisor-observations`はセッション別の最終CLI観測、`findings`は指摘・解決条件・revision・評価を保存します。既存のstoreと同じ所有者専用のディレクトリ0700・ファイル0600を使い、シンボリックリンクや不適切な所有者・権限を拒否します。観測と制御を別レコードにし、readの完了でpause/stopを上書きしません。
+同じホームの`codex-steer/supervisors`はDesktopタスク別の制御、`cloud-supervisors`はCloudタスク別の制御、`supervisor-observations`はセッション別の最終CLI観測、`findings`は指摘・解決条件・revision・評価を保存します。既存のstoreと同じ所有者専用のディレクトリ0700・ファイル0600を使い、シンボリックリンクや不適切な所有者・権限を拒否します。観測と制御を別レコードにし、readの完了でpause/stopを上書きしません。
 
 送信とpause/stopはタスクの監督ロック、指摘の変更と送信履歴はタスクのメッセージロックで直列化します。処理中の競合は`RECORD_BUSY`で明示し、未知の受付結果を自動再送しません。送信受付後に監督状態の書き込みだけが失敗した場合は、配送結果とIDを維持して`supervision_update_required: true`を返します。これは再送の指示ではありません。
 
@@ -218,18 +218,10 @@ npx -y codexteer@0.17.0 --version
 
 開発用の`npm run test:connection`は、Desktop同梱CLIを一時プロファイルのUnixソケットで起動し、ローカル偽モデルで作った合成履歴の読み取りを確認します。実Desktopへの接続・設定変更や外部モデル利用は行いません。`npm run test:protocol`は既存wrapper・偽Desktopとの送信と承認経路、`npm run test:package`は実tarball・オフラインnpx・偽Claude/Codexの起動と、別CODEX_HOME・キャッシュ削除後の観測/送信・pause/resume・重複拒否を確認します。これらの隔離検証から実Desktopの表示や直接接続での承認往復まで保証するものではありません。
 
-## 0.17.0の公開候補
+## 0.18.0の公開候補
 
-`package.json`と`package-lock.json`の版を0.17.0に揃えています。0.16.0はnpm registryで公開済みであることを確認し、同じ版への上書き公開は行いません。`projects list`と`thread create --project`、Desktopの所属登録、全フォルダと初回指示の照合を追加します。既存のruntime protocolとcapability契約はv1を維持します。
+`package.json`と`package-lock.json`の版を0.18.0に揃えています。0.17.0はnpm registryで公開済みであることを確認し、同じ版への上書き公開は行いません。`projects list`と`thread create --project`、Desktopの所属登録、全フォルダと初回指示の照合を追加します。既存のruntime protocolとcapability契約はv1を維持します。
 
 公開前に構文・全回帰・tarballとoffline install・npm/npx・publish dry-runを確認します。公開するファイルを固定する場合は、検証済みtarballのSHA-256を照合してから同じtarballを公開してください。PRのReady化やバージョン更新だけではnpmへ公開されません。
 
-2026-10-15 JSTの公開候補で、次を確認しました。
-
-- `npm ci --offline --ignore-scripts --no-audit --no-fund`、`npm run check`、`git diff --check`が成功。
-- `node --test --test-concurrency=1`は294件成功、失敗・skipなし。内部RPCエラーによる結果不明の回帰試験を含みます。
-- `npm run test:package`が成功。73ファイルのtarball、offline install、npm exec/npx、保存CLI、混在バージョン、publish dry-runを確認。
-- `npm run test:protocol`と`npm run test:connection`が成功。実同梱CLIと偽Desktop・ローカル偽モデルの隔離試験で、実ユーザーのタスクには送信していません。
-- 0.17.0候補CLIから`CODEX_THREAD_ID`なしで「競馬」へのdry-runが成功。7フォルダ、standalone経路、同梱schemaとnative catalogを確認し、チャット・指示・receiptは作成していません。
-
-実Desktopでの作成・所属とCLI終了後の手動承認は[チャット作成の実測記録](thread-create.md)を参照してください。PR確定前の開発作業ツリーで記録した過去の件数と、今回のPRだけを含む294件・73ファイルは検証範囲が異なります。npm公開・Gitタグ作成はこの準備に含みません。
+検証結果の要約は`remote-cli-validation.json`を参照してください。実環境のホスト・プロジェクト・チャット識別子、ローカルパス、診断ログは公開用の配布物へ含めません。npm公開・Gitタグ作成はPR更新とは別の操作です。

package/docs/orchestration.md

@@ -0,0 +1,120 @@
+# プロジェクトと目標からオーケストレーションを始める
+
+`prompt`を付けなければ、生成本文を渡して対話CLIを起動します。
+
+```bash
+codexteer orchestrate --project 'Example Project' '達成したい目標' --use-path-cli
+codexteer orchestrate --project 'Example Project' '達成したい目標' --agent codex
+codexteer orchestrate --project 'Example Project' '達成したい目標' --agent claude -- --model <MODEL>
+```
+
+起動方法は`supervise`と同じで、`--agent`の既定は`claude`です。`codex`も指定できます。これは起動先CLIの選択で、役割の本文はモデル非依存です。起動側は現在のcwd・環境・標準入出力を引き継ぎ、CLIの終了コードを返します。`SIGINT`・`SIGTERM`・`SIGHUP`を転送し、シグナル終了は128+シグナル番号です。
+
+最初の`--`以降はすべて起動するCLIの引数として、順序・空文字・改行を保持して渡します。その後ろにCLI側の`--`と生成本文を一つの引数として追加し、shellで再展開しません。`--json`は直接起動では使えません。本文のJSONが必要な場合は`orchestrate prompt ... --json`を使います。
+
+目標は一つの引用した引数か`-`で渡します。`--`で始まる目標はstdinの`-`を使ってください。stdinの目標は起動前に読み取るため、その入力は対話CLIへ再送しません。通常の引数で目標を渡す場合はstdinもそのまま対話CLIへ引き継ぎます。
+
+`--use-path-cli`は本文内のcodexteerコマンドをPATH方式にし、保存コピーを作りません。省略時は保存済みCLI・Node版・canonical `CODEX_HOME`を本文へ固定します。起動するエージェント自体は、どちらの方式でもPATHから選びます。PATH方式の直接起動でも`CODEX_HOME`の所有者と権限を検証し、必要ならディレクトリを作成します。入力不正や保存コピーの改変、unsafe profileではエージェントを起動しません。
+
+起動側はDesktopへ接続せず、本文を受け取ったオーケストレーターがプロジェクト照合・作成・監視を開始します。プロジェクト用の単一スレッド監督IDは作りません。各子の監督登録と制御は本文の手順に従います。
+
+## 本文だけ生成する
+
+```bash
+codexteer orchestrate prompt --project 'Example Project' \
+  'モーション図鑑で現状の動作を確認し、変更を指示できる状態にする'
+```
+
+生成した本文を同じPCのオーケストレーターへ依頼として渡します。役割はモデルに依存せず、Codex自身もオーケストレーターを担当できます。既存スレッドIDは不要です。特定スレッドを監督するときは、従来の `supervise prompt <THREAD> [MESSAGE]` を使います。
+
+生成ではDesktopへ接続しません。プロジェクトの照合、チャット作成、送信、監督登録、監視は、本文を受け取ったオーケストレーターが開始します。既定ではCLIと依存を内容ハッシュ別に保存・検証し、元のNodeとcanonical `CODEX_HOME`を使うコマンドを本文へ埋め込みます。
+
+```bash
+# 実行環境のPATHとCODEX_HOMEを使う本文。CLIのコピーは作らない
+codexteer orchestrate prompt --project 'Example Project' '達成したい目標' --use-path-cli
+
+# 子の監督IDと送信元のCLI識別を明示する（エージェントは起動しない）
+codexteer orchestrate prompt --project 'Example Project' '達成したい目標' --agent codex
+
+# 改行を含む目標を標準入力で渡す
+codexteer orchestrate prompt --project 'Example Project' - < goal.txt
+
+# 目標が -- で始まる場合
+codexteer orchestrate prompt --project 'Example Project' -- '--から始まる目標'
+
+codexteer help orchestrate prompt
+```
+
+`--project`はローカルでは登録済みプロジェクトのIDか完全一致名です。`--host HOST --remote-transport paired`では接続先の正式ID・Desktop登録ID・一意の完全一致名を使い、host・paired・指定したローカルcallerを子作成/監督コマンドへ保持します。接続先の選択とcaller条件は[リモートのCLI操作](remote-operations.md)を参照してください。生成時は指定文字列を保持し、実行開始時に `projects list` でIDと全rootsを照合します。同名ならIDで特定します。目標は一つの引用した引数か `-` で渡し、空文字・空白だけを拒否します。改行やプレースホルダーを評価せず保持します。
+
+`orchestrate prompt`の`--agent claude|codex`は子の監督IDのownerと送信元を識別する任意指定です。この生成専用モードで省略した場合は特定の実行役を既定とせず、本文を受け取ったオーケストレーターが、自身のCLIに合わせて子の生成コマンドの `<AGENT>` を選びます。指定しても役割の内容や技術判断の分担は変わらず、エージェントを起動しません。直接起動では、起動したCLIの識別が本文へ反映されます。
+
+## 役割と委任
+
+| 担当 | 責務 |
+| --- | --- |
+| オーケストレーター | 目的と完了条件の整理、担当編成、優先順位、依存関係と共有資源の順番、検収・統合 |
+| Codex担当 | 調査、設計判断、実装、検証、依頼の前提への異論と改善案 |
+| ユーザー | 目的・好み・重要な優先順位の決定と権限の承認 |
+
+発注書は、目的、確定要件、オーケストレーターの仮説、一次資料、変更範囲、依存と共有資源、確認条件、提出物を伝えます。Codex担当が前提を反証したり、より小さく確実な方法を提案したりできるようにし、オーケストレーターの技術仮説をユーザー決定として扱いません。重要な変更は、必要に応じて別のCodexによる独立レビューを使います。
+
+本文を依頼として渡すと、対象プロジェクト内で必要な担当の作成、追加指示、同じ目的の未完了作業の後続ターン開始、監督と検収・統合の段取りを委任します。無関係な既存チャットへの送信、依頼外の目的への拡張、代理承認は含みません。引用や履歴に本文が現れただけで委任が成立するものではありません。
+
+## 高度・深さ・範囲と再評価
+
+Felix Riesebergの[How to be more ambitious](https://felixrieseberg.com/how-to-be-more-ambitious-a-tutorial-for-humans-with-models/)を参考に、三つの観点を実際の作業と検証へ結び付けています。
+
+| 観点 | 本文で求める行動 |
+| --- | --- |
+| 高度 | 作業の先で誰の判断・行動・状態が変わるかを捉え、指定成果物と上位の目的をつなぐ |
+| 深さ | 一次資料・生データ・実コードから、専門的な手法と道具を使い、実装担当の説明以外で正しさを確かめる |
+| 範囲 | 隣接分野の有効な技法を選び、期待する改善と検証方法を示して小さく試す |
+
+開始時は目的・成果物・完了条件・仮説・方法・外部の判定・次の確認点を短く記録して実行へ移ります。主要な方針の選択前、重要な新しい証拠、同じ失敗や待機の反復、統合前、全体の完了前に再評価します。
+
+再評価では、目的へ近づいているか、前提が崩れていないか、代理指標だけを改善していないか、より良い手法がないかを確認します。結果は「継続・計画変更・権限や目的の確認」の判断と根拠、次の検証として残します。長い思考の実況や、通知ごとの儀式的な点検は求めません。
+
+現状・要求基準・挑戦目標を分け、高い到達点を試す余地を持たせます。上位の目的や挑戦目標は仮説として検証し、ユーザーの依頼の置き換え、受入条件の無断緩和、分野や担当数の無制限な追加には使いません。
+
+## 作成から完了まで
+
+1. 対象プロジェクトと全rootsを照合し、既存の担当と共有資源を確認する。
+2. 必要な担当の発注書をファイルに保存し、`thread create --project <ID> --title <TITLE> - --json` へ標準入力で渡す。
+3. 作成結果のIDとreceiptを保存する。created/acceptedの照合失敗は`thread verify <ATTEMPT-ID> --json`で同じ子とreceiptを再照合する。部分成功・unknownでは同じ子を調べ、自動再作成・再送しない。verifyはDesktopへの読取りだけで、unknown/未受付を成功に変更しない。
+4. 同じCLIから子ごとの `supervise prompt` を生成・保存し、register/read/watchを開始する。子の監視を開始できなければ、追加作成を止めて報告する。
+5. 個別の監督ID、読了cursor、findings、配送照合を使って介入する。必要な継続は同じ委任の未完了作業に限る。
+6. 最終差分と検証・成果物を検収し、統合と統合後の確認を担当へ依頼して全体の目的達成まで追う。
+
+作成用コマンドは特定スレッドの `--supervisor` を持ちません。子の観測・送信は、生成した個別の監督コマンドを使います。既定の保存済みCLI方式とPATH方式を子の生成にも引き継ぎます。既存監督IDからの `orchestrate prompt` と、観測専用の `--connection desktop` は拒否します。
+
+担当ごとの生成方針には、目的の継続、Codexの独立した判断、三つの観点を含めます。元からある単一スレッド監督の標準方針や操作手順は変更しません。
+
+## 制御と確認範囲
+
+`supervise pause/stop`は個別スレッドの監督制御です。プロジェクト全体の一括pause/stopや常駐スケジューラーは追加していません。オーケストレーターへの監督停止指示は、新規作成・追加送信・自分のMonitor/watchを止める指示として扱い、実行中のCodex担当の作業自体を止める指示とは区別します。
+
+`resource`は参加者間の協調用リースで、OSの強制ロックや公平な待ち行列ではありません。利用順はオーケストレーターが調整します。監督登録がactiveでも、継続して監視できていることを証明しません。
+
+JSON出力は次の形です。`project_selector`は照合前の指定文字列です。
+
+```json
+{
+  "ok": true,
+  "command": "orchestrate.prompt",
+  "data": {
+    "project_selector": "Example Project",
+    "goal": "達成したい目標",
+    "agent": null,
+    "prompt": "目標・役割・再評価と操作手順を含む本文…",
+    "connection": "shared",
+    "cli_mode": "path",
+    "deployment": null,
+    "node": null
+  }
+}
+```
+
+既定の `cli_mode: saved` は、`supervise prompt`と同じdeploymentとnodeのメタデータを返します。生成時にプロジェクト用の監督IDや登録記録は作りません。
+
+自動テストは、CLIの入出力、生成時の非接続、目標と方針の分離、引数の保持、CLI方式の継承と子の監督開始、既存監督の回帰を確認します。生成成功は、受け取るAIの方針遵守や実プロジェクトの目的達成を証明するものではありません。

package/docs/remote-cli-validation.json

@@ -0,0 +1,139 @@
+{
+  "validation_scope": "Public aggregate results only. Test identifiers and fixture hosts are synthetic; no account metadata or conversation content is included.",
+  "transport": "paired",
+  "pull_request_validation": {
+    "tests": 409,
+    "pass": 408,
+    "fail": 0,
+    "skipped": 1,
+    "syntax": "passed",
+    "diff_check": "passed",
+    "package": {
+      "suite": "package",
+      "result": "PASS",
+      "package": "codexteer",
+      "version": "0.17.0",
+      "packed_files": 101,
+      "publish_dry_run": true,
+      "offline_install": true,
+      "npm_exec": true,
+      "npx_supervision": true,
+      "copied_prompt": true,
+      "cache_update": true,
+      "cache_removal": true,
+      "mixed_versions": true,
+      "feature_isolation": true,
+      "real_desktop_validated": false
+    }
+  },
+  "pause_stop_regression": {
+    "date": "2026-10-28",
+    "scope": "Local temporary state, fake remote RPC and synthetic commands only. No real enrollment, pairing or chat sends.",
+    "before_fix": {
+      "tests": 4,
+      "pass": 1,
+      "fail": 3,
+      "result": "Acknowledged pause/stop during preparation did not prevent shell dispatch; resource execution dropped supervisor binding."
+    },
+    "after_fix": {
+      "tests": 7,
+      "pass": 7,
+      "fail": 0,
+      "result": "Pause/stop before dispatch rejects execution. Dispatch holds the supervisor control lock through the RPC receipt; concurrent control returns RECORD_BUSY. The lock releases after the receipt. Unknown execution retains resource lease without replay."
+    },
+    "test_file": "test/supervised-shell.test.mjs",
+    "accepted_commands_cancelled_by_pause": false,
+    "real_chat_messages_sent": false
+  },
+  "dependency_advisory_audit": {
+    "checked_at_utc": "2026-10-28T02:29:39Z",
+    "scope": "Installed and bundled npm dependencies from package.json, package-lock.json and npm ls --all. One package: ws 8.21.3; no transitive dependencies. Optional peers bufferutil/utf-8-validate are not installed or bundled.",
+    "npm_version": "11.20.0",
+    "databases": [
+      {
+        "name": "npm Audit",
+        "matching_vulnerabilities": 0,
+        "severity_counts": {
+          "info": 0,
+          "low": 0,
+          "moderate": 0,
+          "high": 0,
+          "critical": 0,
+          "total": 0
+        },
+        "command": "npm audit --json --registry=https://registry.npmjs.org",
+        "registry": "https://registry.npmjs.org/"
+      },
+      {
+        "name": "OSV",
+        "endpoint": "https://api.osv.dev/v1/query",
+        "query": {
+          "package": {
+            "name": "ws",
+            "ecosystem": "npm"
+          },
+          "version": "8.21.3"
+        },
+        "matching_vulnerabilities": 0
+      },
+      {
+        "name": "GitHub Advisory Database (reviewed)",
+        "endpoint": "https://api.github.com/advisories?ecosystem=npm&affects=ws%408.21.3&type=reviewed&per_page=100",
+        "matching_vulnerabilities": 0
+      }
+    ],
+    "positive_control": {
+      "database": "OSV",
+      "queried_not_installed_version": "ws 8.20.0",
+      "matching_advisories": [
+        "GHSA-58qx-3vcg-4xpx",
+        "GHSA-96hv-2xvq-fx4p"
+      ],
+      "note": "Read-only API query; vulnerable version was not installed or executed."
+    },
+    "distribution_integrity": {
+      "name": "ws",
+      "version": "8.21.3",
+      "registry_integrity_matches_lockfile": true,
+      "installed_files_match_registry_tarball": true,
+      "files_compared": 19
+    },
+    "remediation": "No known affected dependency found; retain the existing exact pin and lockfile.",
+    "limitations": "Point-in-time known-advisory check, not proof of absence of unknown vulnerabilities. External Node/npm runtimes, Codex Desktop/native addons and OS components are not project npm dependencies and were not audited against their own advisory feeds.",
+    "real_chat_messages_sent": false,
+    "audited_dependency_tree": "package-lock.json: ws 8.21.3"
+  },
+  "publication_review": {
+    "date": "2026-10-28",
+    "scope": "Public source tree, PR-only commits, PR description/comments, and npm tarball. Environment-specific investigation records are excluded.",
+    "secret_scanner": {
+      "name": "Gitleaks",
+      "version": "8.30.1",
+      "configuration": "Built-in rules; ignore-allow comments disabled; no repository suppression list.",
+      "credential_findings": 0
+    },
+    "privacy_controls": [
+      "Examples and tests use synthetic UUIDs and fixture names only.",
+      "No personal home paths, real workstation names, real project/chat IDs or conversation transcripts.",
+      "Investigation notes excluded from the repository publication tree and npm file allowlist.",
+      "Local authentication, environment and diagnostic files ignored by Git."
+    ],
+    "regression_tests": "test/publication.test.mjs",
+    "limitations": "No scan proves absence of unknown secret formats. Removing current files or rewriting PR-only commits does not erase earlier base-branch history, third-party clones or hosting-provider caches."
+  },
+  "review_follow_up": {
+    "scope": "Remote CLI parent branch; temporary profiles and fake RPC only. No real host or conversation operations.",
+    "targeted_tests": 68,
+    "targeted_pass": 68,
+    "fixed": [
+      "POSIX case-sensitive project and scope comparisons; explicit Windows drive/UNC handling",
+      "Positional destination routing independent of metadata option values",
+      "Reject mismatched supervisor transport before pause/resume/stop writes",
+      "Persist failed remote reverification and clear stale certification flags",
+      "Keep internal execution RPC errors unknown and retain resource leases without replay",
+      "Japanese Unreleased changelog entries"
+    ],
+    "previously_fixed": "Supervised shell dispatch remains serialized with pause/stop; seven existing regression tests pass.",
+    "github_test_ci": "No repository test workflow configured; local regression/package suites executed."
+  }
+}

package/docs/remote-control.md

@@ -0,0 +1,65 @@
+# リモートへの指定ターン送信と監督
+
+`--remote-transport control`を明示すると、Remote Control WebSocket protocol v3のフレーム内にApp Server JSON-RPCを載せ、`remote-control:env_...`で選んだホストへ直接送ります。`turn/steer`の`expectedTurnId`をそのままリモートApp Serverに渡し、サーバーが現在のターンと照合します。Desktopのnative `send_message_to_thread`やfollower操作による、宛先ターンの推測は使いません。
+
+**control経路は実験的な実装です。** 既存Desktop鍵をhelperから利用できない環境では、接続前の公開鍵診断で停止します。control経路の動作確認は利用環境ごとに必要です。鍵へのアクセス権を変更したり別の鍵へ自動切替したりしません。
+
+Desktop鍵に限定しない場合は、[専用端末鍵を公式登録するpaired経路](remote-device-enrollment.md)を明示選択できます。native / control / paired間で資格情報やカーソルを自動的に切り替えません。
+
+```bash
+# 対象を読み取りだけで診断する。送信や再開はしない。
+codexteer --remote-transport control doctor --thread '<hostId付きリンク>' --json
+
+# 送信を伴う監督用の本文を生成する。本文生成だけでは接続しない。
+codexteer --remote-transport control supervise prompt '<hostId付きリンク>' --use-path-cli
+
+# 監督役を起動する。明示した方針と目的の範囲内で、既存のactiveターンへ介入する。
+codexteer --remote-transport control supervise '<hostId付きリンク>' --agent codex
+
+# 同じ経路で読み、カーソルと指摘を登録してから送信する。
+codexteer --remote-transport control read '<hostId付きリンク>' --json
+codexteer --remote-transport control findings create '<hostId付きリンク>' \
+  --key '<安定したkey>' --title '<指摘>' --condition '<解決条件>' --based-on '<CURSOR>' --json
+codexteer --remote-transport control send '<hostId付きリンク>' '<指示>' \
+  --finding '<FINDING-ID>' --based-on '<CURSOR>' --source codex --kind review --json
+```
+
+control経路は通常の端末からの利用も想定した実装で、`--context-thread`は不要です。リモートリンクか`--host remote-control:env_...`は必須です。`--remote-transport`を省略した既存のnative経路は、引き続き観測専用です。接続失敗時にnative送信、UI、SSH、別ホストへ切り替えません。SSHホストやChatGPT cloudのIDをRemote ControlのIDへ読み替えません。
+
+## 接続・認証と照合
+
+1. 選択したCODEX_HOMEの既存shared wrapperと、同梱CLIのcommand schemaを検証する。
+2. 正規App Serverの`getAuthStatus`を読み、現在の標準ChatGPTアカウントを特定する。トークンはメモリ内だけで扱う。
+3. 同じトークンのaccount userまたはDesktopが受け付けるauth user aliasに一致する既存Desktop device-key enrollmentを読み取る。account headerはトークンのaccount IDに固定する。新規キー・登録・設定変更を行わない。
+   固定helperのinspect操作で既存公開鍵を照合する。失敗すればREMOTE_DEVICE_KEY_UNAVAILABLEとremote_control_auth診断を返し、WebSocketを開かない。この操作は署名しない。
+4. `wss://chatgpt.com/backend-api/codex/remote/control/client`だけにTLSで接続し、HTTP Authorizationと`ChatGPT-Account-Id`を使う。URL変更・リダイレクト・別の認証方式へのfallbackを行わない。
+5. `x-codex-protocol-version: 3`と`x-codex-client-auth: socket-refresh-v1`を指定し、目的・宛先origin/path・アカウント・client・scope・nonce・有効期限が一致した認証チャレンジだけを受け付ける。purposeとaudienceは`remote_control_client_websocket`、scopeは`remote_control_controller_websocket`で別の値である。socket-refresh未対応なら停止する。
+6. 固定のhelperをDesktopの署名付きNodeから読み取り専用sandboxで起動する。OSの非抽出キーを既存登録の公開鍵と照合し、許可した接続チャレンジだけへ、定義したフィールド順に正規化して署名する。秘密鍵はエクスポートしない。helperの入出力と一時ファイルへbearer tokenを渡さない。
+7. 署名を登録済み公開鍵で検証し、`device_key_authenticated`が返った場合だけ専用のstream IDを開く。
+8. すべての読み取り・送信前にローカルのアカウントとenrollment、選択中runtimeが変わっていないことを確認する。各フレームのclient・env・stream・連番と分割ペイロードを検査し、選んだホスト以外の履歴や受付結果を採用しない。
+
+この経路の利用は、既存ログイントークンを上記の公式宛先へ送信し、登録済みOSキーで接続チャレンジへ署名する操作を伴います。OSやDesktopの認証拒否を解除・迂回せず、そのまま停止します。通常起動の`--connection desktop`は引き続き観測専用で、controlとの併用は拒否します。
+
+## ターン照合と監督の制約
+
+既存の`readSendState`・`sendOnClient`と同じ処理で最新のactiveターンを選び、`threadId`・`expectedTurnId`・`clientUserMessageId`を固定して一度だけ`turn/steer`します。ターンが入れ替わればサーバーの拒否を返します。別のターンを選び直して再送しません。transportのACKをメッセージ受付と解釈せず、App Serverの同じturn IDの応答でだけacceptedにします。
+
+監督ID・finding・読了カーソル・ユーザー入力の更新確認・pause/stopのロック・重複介入防止・配送記録は既存の処理を使います。unknownはclient message IDを持つ実際の履歴と`history check`で照合し、not_observedを未配送と決めつけません。接続の再開時も送信フレームをreplayしません。手動の新しい送信も、委任されたメッセージや監督の範囲内で行います。
+
+controlとnativeでは公開履歴の項目構造・出力制限が異なるため、カーソルと監督登録を`remote_transport`にも結び付けます。同じhostIdでも別経路のカーソルや監督IDを使うと停止します。既存nativeのカーソルにremote_transportがない場合はnativeとして扱います。送信履歴と指摘は同じホストの対象として共有し、経路を変えて重複送信を回避しません。
+
+- `--new-turn`、`thread/resume`、`turn/start`は未対応。別接続から新規ターンを始めて承認の所有者を失わないよう拒否する。
+- UI送信、代理の承認回答、作成、履歴修復は未対応。
+- 送信JSONは64 KiBまで。大きすぎる要求は配送前に拒否する。
+- 応答はフレームごとに150 KiB、再構成後64 MiBまで。欠落・順序異常・別ホストのフレームは停止する。
+- 接続・認証・schemaの対応状況と、指示の実配送・UI表示・承認往復は別々に扱う。
+
+## 鍵が利用できない場合
+
+`doctor`が`REMOTE_DEVICE_KEY_UNAVAILABLE`を返す場合、`remote_control_auth`の失敗段階と分類を確認してください。これは鍵がDesktopからも消えている証拠ではありません。Desktopの署名・Keychain ACL・entitlementを変更せず、必要なら利用者が専用鍵のpaired方式を別途選択してください。診断や登録の許可は、チャットへの指示送信の許可を意味しません。
+
+## 検証
+
+`test/remote-control.test.mjs`では、テスト用EC鍵・架空のトークン・フレームを使い、チャレンジと署名の照合、別アカウント/宛先/期限/ホストの拒否、ターン交代拒否、unknown配送とreplay禁止、idle/new-turn拒否、freshness・pause/stop・findingの重複拒否、client IDでの保存履歴照合、保存済みCLIとPATH版の監督本文を検証します。実アカウントは使いません。
+
+`npm run test:remote-control`は一時プロファイルの実同梱Rust App Serverとloopbackの偽モデルを使います。Remote Controlフレームのadapterを通した正しいターンの受付と、誤ったexpectedTurnIdのサーバー側拒否、送信前freshnessの照合を確認済みです。公式ゲートウェイ、実トークン、実device keyは使いません。

package/docs/remote-device-enrollment.md

@@ -0,0 +1,91 @@
+# codexteer専用端末鍵の登録とペアリング
+
+`--remote-transport paired`はcodexteer専用の端末鍵と登録を使います。既存Desktop鍵を使う`control`と、Desktop接続で観測する`native`から明示的に区別します。登録・ペアリングは利用者が実行するセットアップ操作であり、read / doctor / 監督から自動では行いません。
+
+## 手順
+
+Mac上で専用鍵を準備します。次のkeychain方式はXcode command-line toolsが必要です。
+
+```sh
+codexteer remote prepare --key-provider keychain --json
+codexteer remote enroll --json
+codexteer remote verify --json
+```
+
+`remote enroll`は公式ブラウザにfreshな本人認証を要求します。ブラウザは`https://auth.openai.com/oauth/authorize`だけを開きます。パスワードやトークンをチャットやCLI引数へ渡さず、公式画面で認証します。登録用スコープは`codex.remote_control.enroll`です。PKCE S256、state、localhostの公式コールバックポート1455 / 1457を使い、得たトークンのアカウント・スコープ・発行時刻・password auth timeを照合します。既存の通常ログイントークンを登録用step-up tokenとして代用しません。
+
+対象WindowsホストのDesktopで、Settings → Connections → Control this PC → Set up / Addからペアリング画面を開きます。Computer向けのPIN表示へ切り替えるなどして手動ペアリングコードを取得します。CLIの追加インストールは不要です。
+
+公式CLIを利用できる環境では、Desktopと同じプロファイルで次の方法も使えます。別プロファイルを起動したり、ホストのdaemonを再起動する必要はありません。
+
+```sh
+codex remote-control pair
+```
+
+Mac上の端末で次を実行し、発行したコードを入力します。TTY入力は非表示で、Enterで確定します。コードはargv・履歴JSON・専用登録ファイルには保存しません。パイプ入力も利用できますが、コードをshell履歴や共有ログに残さないようにしてください。
+
+```sh
+codexteer --host 'remote-control:env_example' remote pair --code-stdin --json
+codexteer remote verify --json
+codexteer --remote-transport paired doctor --thread '<hostId付きリンク>' --json
+codexteer --remote-transport paired read '<hostId付きリンク>' --json
+```
+
+ペアリングAPIはコードが指すホストを認可します。応答のenvironment IDが指定hostと異なれば`REMOTE_PAIR_HOST_MISMATCH`で報告し、指定チャットを開きません。これはペアリング前の原子的なhost照合ではありません。入力するコードが指定ホストで発行されたものかを確認してください。`remote verify`は専用clientに許可されたホスト一覧を公式APIで再照合します。
+
+Windows環境が`remote-control:env_example`なら、Mac側の`--host`へその値をそのまま使います。
+
+## 鍵方式
+
+| 明示する方式 | 実装と保護 | 制約 |
+| --- | --- | --- |
+| `remote prepare --key-provider openai-native` | Desktop同梱の未変更native addonを署名済みNodeで実行し、新しい専用鍵を作る。公式のhardware / OS非抽出policyを使用 | ハードウェアとOS権限に依存する。利用できない場合は停止する |
+| `remote prepare --key-provider keychain` | codexteer自身のSwift helperをローカルビルド・アドホック署名し、ログインキーチェーンに非抽出P-256鍵を作る。OSのSecKey属性で非抽出・256bitを確認し、公開鍵だけをSPKIへ変換 | Secure Enclaveとは表示しない。OSのキーチェーン確認要求には利用者が対応する |
+
+方式を失敗時に自動切替しません。準備済みの鍵を別方式で置換する要求は`REMOTE_KEY_PROVIDER_MISMATCH`で停止します。Desktop本体・同梱Nodeの署名やentitlementは変更しません。keychain方式のhelperにも、Desktopのアクセスグループや特権entitlementは追加しません。
+
+helperはsecret keyのexport APIを呼びません。OSに非抽出属性を設定し、返されたSecKey属性がfalseであることを確認できた鍵だけを登録へ進めます。属性を確認できない候補では登録を拒否します。単に生成引数を渡したことを非抽出性の証明にはしません。
+
+## 保存・中断と再検証
+
+専用登録は、選んだCODEX_HOMEの`codex-steer/remote-device/<accountのSHA256>.json`へowner-onlyで保存します。含まれるのはアカウント識別子、client ID、公開鍵メタデータ、OS key ID、登録phase、ペアリング先です。Desktopの`.codex-global-state.json`は更新しません。bearer / OAuth step-up / remote-control token / pairing code / 署名proofは保存しません。
+
+Swift helperは`remote-device/key-helpers/<source hash>/`へ保存し、実行ごとに所有者・mode・binary hash・コード署名を検査します。登録にはそのruntimeを固定し、更新時に鍵を使うhelperを勝手に作り直しません。使用中のruntimeを削除しないでください。
+
+```sh
+codexteer remote status --json
+codexteer remote recover-key --json
+codexteer remote verify --json
+```
+
+- `prepared`は鍵だけの準備完了。まだサーバー登録はありません。ブラウザ認証の中断はこの鍵を保持します。
+- keychainの`creating-key`は鍵作成の結果が未確定。保存済みcandidate key IDの`recover-key`で同じ鍵を照合します。新規作成はしません。
+- `starting` / `creating-key` / `key-created`でサーバーclient IDを取得済みのものは、未完了の登録です。別clientや鍵を自動作成しません。
+- `finish-unknown`は登録完了応答が未確定。`remote verify`は同じ鍵とclient IDで認証だけを確認し、成功すればenrolledへ進めます。finish要求は再送しません。
+- ペアリング応答不明は`pairing_unknown`。同じコードを自動再送せず、`remote verify`で公式の許可ホスト一覧を読み直します。
+
+`remote verify`のWebSocket操作は認証proofだけで、App Server initializeやチャットRPCは送りません。別途pairedのdoctor/readを実行して初めて、その対象の読み取りを検証します。
+
+## 監督との接続
+
+paired接続は既存のRemote Control v3 adapterを使い、送信には同じ`turn/steer.expectedTurnId`照合、freshness、pause/stop、finding重複防止、配送照合を適用します。native / control / pairedのカーソル・監督IDは交換できません。専用登録がない場合や指定ホストがペアリングされていない場合は、外部socketを開かずに停止します。失敗時にDesktop鍵へ切り替えません。
+
+登録・ペアリングと、チャットの作成・送信は別々に利用者が許可する操作です。対象のホスト・プロジェクト・チャットを確認し、許可された範囲だけで使ってください。callerと購読条件は[リモートCLI操作](remote-operations.md)を参照してください。監督役から資格情報セットアップは実行できません。
+
+## 端末名とサーバー表示の照合
+
+従来のWebSocketは`User-Agent: codexteer`しか送らず、同じ専用clientのサーバー表示は`Unknown Computer`・platform nullでした。HTTPとWebSocketへcodexteerの製品名・実OSバージョン・CPUを送るよう変更しました。macOSでは固定の`/usr/bin/sw_vers -productVersion`から取得し、失敗・不正値はバージョンなしへ限定します。OSの識別のためにDesktop製品を名乗りません。
+
+```sh
+codexteer remote status --json
+codexteer remote verify --json
+codexteer remote identity --json
+```
+
+`controller_name`は`codexteer_mac_os_arm64`などのCLI側の識別名です。`remote identity`は公式アプリが使う`GET /wham/remote/control/clients`を読み、同じ専用clientだけを選別して`server_display_name`・OS・端末種別を返します。他端末・アカウントユーザー・位置情報は出力しません。identity自体は接続や名前変更を行いません。
+
+任意のクライアント表示名の更新は未対応です。`name_matches`と`custom_name_update`でローカル識別名とサーバー表示の違いを明示します。表示名を合わせるための自動再登録・鍵置換・ホスト名変更は行いません。
+
+## 互換性
+
+登録とペアリングの経路はDesktopのバージョンに依存します。外部CLI向けの安定した登録SDKであるとは扱いません。schemaの変更や認証拒否では停止し、利用環境で確認してください。秘密値や実際の識別子を含む診断記録は公開しないでください。

package/docs/remote-observation.md

@@ -0,0 +1,57 @@
+# リモートプロジェクトとチャットの観測
+
+`projects list --remote`でDesktopに登録済みのリモートプロジェクトを取得できます。`hostId`付きリンクは、そのホストのチャットとして読み取り・監視・観測専用の監督に使えます。この文書の既定native経路では、指示送信・再開・作成・履歴修復は未対応です。指定ターンへの送信は、別途明示する[control経路](remote-control.md)に実装しています。controlの認証チャレンジ受信まで確認済みですが、既存端末鍵へのアクセスで停止しています。
+
+```bash
+codexteer projects list --remote --json
+codexteer projects list --all --json
+codexteer projects list --host 'remote-control:env_example' --json
+
+codexteer read 'codex://threads/<UUID>?hostId=remote-control%3Aenv_example' --json
+codexteer doctor --thread 'codex://threads/<UUID>?hostId=remote-control%3Aenv_example' --json
+codexteer watch 'codex://threads/<UUID>?hostId=remote-control%3Aenv_example' --stream --json
+codexteer supervise 'codex://threads/<UUID>?hostId=remote-control%3Aenv_example' --agent codex
+codexteer supervise prompt 'codex://threads/<UUID>?hostId=remote-control%3Aenv_example' --use-path-cli
+```
+
+UUIDと`--host HOST-ID`を別々に指定しても同じ対象になります。リンクの`hostId`と`--host`が矛盾した場合は`HOST_MISMATCH`で停止します。裸のUUIDは従来どおりローカルです。ホストの省略を補うために別ホストを検索しません。
+
+## プロジェクト一覧
+
+引数なしの`projects list`は従来どおりローカルApp Serverのcanonical ID・全rootsを返します。`--all`はその一覧とリモート登録一覧を併合します。`--remote`またはリモートの`--host`はローカルApp Serverへ接続せず、選択した`CODEX_HOME/.codex-global-state.json`の`remote-projects`だけを読みます。状態ファイルを更新しません。
+
+リモート項目はDesktopの登録ID、登録名、remotePath、host_idを返します。Windows/UNCパスをMacのパスへ変換・realpathしません。`source: desktop-registration`と`availability: unverified`は登録情報であり、接続・リモート上の存在・Git判定を確認していないことを示します。今回確認したDesktopのnative `list_projects`はリモートGitメタデータの取得に失敗した項目を省略するため、それを完全な登録一覧として使いません。空配列もリモート上にプロジェクトがないという証明ではありません。
+
+## 読み取りの前提
+
+Desktopが接続済みの対象ホストを、既存shared wrapperの署名付きNode helperからnative `read_thread`で読みます。既存のnative認証・ソケット所有者検査・matching bundled command schema・live native catalogの検証を使います。別のリモート接続、認証情報のコピー、SSH、モデルの中継ターン、Desktopの再起動は行いません。`--connection desktop`との併用は`HOST_CONNECTION_MISMATCH`です。
+
+native toolには実在するローカル呼出し元と保存済みターンが必要です。Codexチャット内では`CODEX_THREAD_ID`を使います。普通の端末から実行する場合は、同じプロファイルの既存ローカルチャットを明示します。
+
+```bash
+codexteer --context-thread '<LOCAL-CALLER-UUID>' read '<HOST-LINK>' --json
+codexteer --context-thread '<LOCAL-CALLER-UUID>' supervise '<HOST-LINK>' --agent codex
+```
+
+このcontextはnative呼出しの関連付け用です。呼出し元へのメッセージ送信・新しいターン作成は行いません。未指定・リモートのcontext・保存済みターンのないcontextは拒否します。対象チャットの応答hostIdが選択先と異なった場合も、結果を採用せず停止します。
+
+native履歴は10ターン単位で全ページを読み、既存のイベント差分・カーソルを生成します。最大100ページ（1000ターン）を超える場合や、ページの重複・不完全なturnでは部分履歴を完全な結果として返しません。コマンド出力とdiffはDesktopが項目ごとに最大20000文字へ制限するため、その場合は`[truncated by Desktop]`を付けます。思考内容は公開イベントに含めません。履歴が大きいチャットは読み取りに時間がかかります。`watch --stream`のキャンセルは次の境界で終了し、未完了のnative読取helperは最大30秒でタイムアウトします。
+
+## 監督の範囲と記録
+
+既定native経路で生成するプロンプトは`observation_only: true`です。既定の方針も観測・問題報告用になります。`--host`、`--context-thread`、`--supervisor`、`--connection`を全コマンドに保持します。明示した方針が送信を求めても、リモートへの送信は`REMOTE_READ_ONLY`で拒否します。Desktopのnative送信APIでは`expectedTurnId`照合と暗黙のターン開始禁止を指定できないため、既存の送信制約を省略して対応扱いにはしません。
+
+監督記録・指摘・履歴・ロックは`CODEX_HOME/codex-steer/hosts/<host-idのSHA256>/`でホスト別に保存し、記録には`host_id`を付けます。既存ローカル記録の場所は変えません。カーソルもhost_idに結び付け、別ホストやローカルのものは`STALE_CURSOR`です。
+
+```bash
+codexteer --host 'remote-control:env_example' supervise list --json
+codexteer supervise status '<HOST-LINK>' --json
+codexteer supervise pause '<HOST-LINK>' --json
+codexteer supervise stop '<HOST-LINK>' --json
+```
+
+`pause`後も観測できます。`stop`後はその監督の観測を拒否し、対象Codexの作業は継続します。`doctor`はリモート読み取りの検証結果と送信未対応を分けて返します。診断成功は指示配送・画面表示・承認往復を保証しません。
+
+## 検証
+
+自動テストは架空のホストと一時プロファイルを使い、複数ページの読取り、別ホストの応答拒否、カーソル・監督記録・停止制御のホスト分離を確認します。実際のホスト名・業務タイトル・チャットID・応答本文は公開記録に含めません。環境ごとの接続条件は利用者自身の`doctor`結果で確認してください。