codexteer 0.18.2 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 公開日は日本時間です。
 
+## 0.19.0 — 2026-11-01公開
+
+- タスクIDと接続指定の不一致エラーに、修正用の`--connection`とJSONの`expected_connection`・`connection`を追加しました。Desktop Cloudには`desktop-cloud`、Web Cloudには`cloud`、ローカルには既定の`shared`を示します。拒否・終了コード・既存エラーコードを維持し、自動切り替えは行いません。
+- `help`の全30トピックを同じ構成に揃えました。各トピックは使い所・使い方・オプション（既定値）・確認できること・エラーと対処・手順・例・補足・関連を持ち、`--json`でも同じ項目名で取得できます。記述は実装と照合し、実装と食い違っていた説明（接続ソケットのリンク、Cloudの版確認の範囲、`status`の`unregistered`など）を直しました。`help desktop-cloud`と`help environments`の「使い所: undefined」表示と、`checkpoint run`・`resource run`の`--json`を`--`の後ろに示していた使い方表示も直しました。トピック名は変わりません。
+- 文言や内部実装に固定されていたテストを整理し、ヘルプの記述とエラーコード・オプションの対応を検査するテストを追加しました。
+- Desktop Cloudで受付不明の送信・プロジェクト割り当てが残ると、以後の送信・`thread assign`が永久に拒否される問題を修正しました。Desktopのプロフィール状態で割り当てを確認できた記録は自動で確定します。確認できない記録は、ユーザーが`history mark <TASK> <MESSAGE-ID> --resolve-unknown --note TEXT`または`thread receipt <ATTEMPT> --resolve-unknown --note TEXT`で理由を残して解除できます（`--supervisor`付きは`SUPERVISOR_CONTROL_FORBIDDEN`）。記録がないことを未配送の証拠にはしません。解除した送信は、結び付いた指摘でも受付不明として扱いません。拒否エラーには解除対象の`existing_message_id`・`existing_attempt_id`を含めます。
+- ローカルの`send`が、`--`より前の未知のオプション（`--kidn`などの打ち間違い）を本文として送っていた問題を修正し、`OPTIONS_INVALID`で拒否するようにしました。`--`より後ろは従来どおり本文です。
+- ローカルの`resource`で、`--supervisor`付きの`acquire`・`renew`・`release`・`status`・`list`が監督状態を確認していなかった問題を修正しました。`--supervisor`付きは`--thread`が必須になり、停止済み・別セッションは拒否、一時停止中は`acquire`・`renew`・`run`を`SUPERVISOR_PAUSED`で拒否します。
+- ローカルタスクへの`diff`が送信の省略形として解釈されていた問題を修正し、接続前に`OPTIONS_INVALID`で拒否します。
+- コードを持たなかった利用者向けの失敗に、エラーコードを付けました（`OPTIONS_INVALID`、`MESSAGE_NOT_FOUND`、`CHECKPOINT_NOT_FOUND`、`INSTRUCTION_NOT_REPLACEABLE`、`RESOURCE_NOT_OWNED`、`TASK_IDLE`、`TASK_BUSY`、`DESKTOP_START_UNSUPPORTED`、`DESKTOP_ALREADY_RUNNING`、`DESKTOP_START_FAILED`、`DESKTOP_UI_NOT_READY`、`DESKTOP_UI_FAILED`、`CURSOR_TOO_LARGE`、`STORE_UNSAFE`など）。実行中のターンがない送信と、idleでないタスクへの`--new-turn`は、`NOT_SENT`ではなく`TASK_IDLE`・`TASK_BUSY`になります。中断したローカルの`checkpoint run`・`resource run`は`error_code: CANCELLED`を返します。
+
 ## 0.18.2 — 2026-11-01公開
 
 - 停止済みの監督IDが、別の監督への交代後に古い本文から再登録できる問題を修正しました。停止履歴を監督記録に保持し、登録前のdoctor・再登録・観測・送信で`SUPERVISOR_STOPPED`を返します。旧形式の停止済み記録も、交代時に履歴へ引き継ぎます。保存済み旧CLIを使う監督には、更新後のCLIでプロンプトを生成し直してください。

package/README.md

@@ -48,6 +48,8 @@ npx -y codexteer@0.18.0 supervise <thread-id>
 
 DesktopのCloud環境構成は、`codexteer --connection desktop-cloud environments list --json`で取得します。新規作成は`thread create --environment <ID_OR_EXACT_NAME>`、継続・監視・監督は`durable_`付きIDまたは`hostId=durable`付きリンクで共通コマンドを使います。所属情報と登録APIの可否は`doctor --thread ... --project ...`で区別します。公式の署名付き`thread assign`は対象がそのDesktopの実行環境を使う場合に限り利用でき、通常のCloud環境では`--project`付き作成を現在も事前拒否します。[操作・確認済み範囲と制限](docs/desktop-cloud.md)
 
+タスクと明示した接続が合わない場合は拒否し、エラー文に修正用の`--connection`、JSONの`error.expected_connection`に修正候補、`error.connection`に今回の指定値を返します。`durable_`付きID・`hostId=durable`付きリンクには`--connection desktop-cloud`、Web Cloudの`task_`付きID・公式リンクには`--connection cloud`を使います。ローカルUUIDには既定の`--connection shared`を候補として示します。ローカルの観測には`--connection desktop`も利用できますが、送信には使えません。明示指定を自動で切り替えることはありません。
+
 ### Codex Cloudを使う
 
 CloudタスクのID・公式リンクで、同じ`supervise`・`read/watch`・`send`・`history/instructions/findings`を使えます。監督の`pause/resume/stop`や保存済みCLIも共通です。接続先をまだ選んでいない一覧と作成は`--connection cloud projects list`・`threads list`・`thread create --project <ENV_ID>`を使います。実行中のCloud送信は同じタスクの元ターンを中断して後続ターンを開始する方式です。[操作とサービス上の違い](docs/cloud.md)

package/docs/distribution.md

@@ -7,6 +7,8 @@
 
 `0.18.2`は、監督が交代した後も停止済みIDを履歴に保持し、古い本文からの再登録・観測・送信を`SUPERVISOR_STOPPED`で拒否します。登録前の`doctor`にも同じ判定を適用します。同じIDの別タスクへの登録を拒否し、旧版で重複したIDを持つ記録も`supervise list --json`で全件と衝突先を返します。該当タスクはそれぞれ`supervise stop`で停止できます。更新前の停止済み記録は交代時に引き継ぎますが、すでに上書きされて失われた停止履歴は復元できません。保存済み旧CLIには修正が反映されないため、更新後のCLIで監督を起動し直すか、プロンプトを生成し直してください。runtime protocolとcapability契約はv1を維持し、Desktopの再起動は必要ありません。
 
+`0.19.0`は、`help`の全トピックを同じ構成に揃えて実装と照合し、Desktop Cloudで受付不明の記録が残ると以後の送信・割り当てが止まる問題、ローカル`send`の未知オプションの送信、`--supervisor`付きローカル`resource`の監督状態の未確認を修正します。利用者向けの失敗にはエラーコードを付けました。実行中のターンがない送信の`NOT_SENT`は`TASK_IDLE`・`TASK_BUSY`に変わるため、コードで分岐している呼び出し側は更新してください。runtime protocolとcapability契約はv1を維持し、Desktopの再起動は必要ありません。保存済み旧CLIで動く監督には反映されないため、更新後のCLIで監督を起動し直すか、プロンプトを生成し直してください。
+
 `package.json` は `private` を持たず、`publishConfig` でnpm公式レジストリへのpublic公開を指定しています。公開可能な設定であることと、実際に公開済みであることは別です。
 
 公開後の基本的な実行形式は次のとおりです。通常はバージョン指定なしで使えます。監督開始後は保存したCLIを使い続けるため、監督中の一貫性を保つために版を明示する必要はありません。起動側と操作側の製品バージョンも、必要な通信仕様が対応していれば異なっていても使えます。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexteer",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "Send steering messages to running Codex Desktop threads from a terminal.",
   "type": "module",
   "bin": {

package/src/app-server.mjs

@@ -74,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 eligible active turn. Read it again before sending; use --new-turn only for an idle task.");
+    if (!turn) throw Object.assign(new Error("The task has no eligible active turn. Read it again before sending; use --new-turn only for an idle task."), { code: "TASK_IDLE" });
     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,7 +84,7 @@ export async function sendOnClient(client, threadId, message, { newTurn = false,
     if (accepted?.turnId !== turn.id) throw new RpcFailure("App Server returned an unexpected turn ID. Do not retry automatically.", { code: "PROTOCOL_ERROR", uncertain: true });
     return { turn_id: accepted.turnId, client_message_id: clientUserMessageId };
   }
-  if (!["idle", "notLoaded"].includes(thread.status?.type) || thread.turns.some(turn => turn.status === "inProgress")) throw new Error("--new-turn requires an idle task. Nothing was sent.");
+  if (!["idle", "notLoaded"].includes(thread.status?.type) || thread.turns.some(turn => turn.status === "inProgress")) throw Object.assign(new Error("--new-turn requires an idle task. Nothing was sent."), { code: "TASK_BUSY" });
   // Resume through Desktop's long-lived connection so approval ownership
   // survives the short-lived sender. Never resume only on the sender connection.
   if (!subscribe) throw new Error("Desktop subscription support is required for --new-turn.");
@@ -93,7 +93,7 @@ export async function sendOnClient(client, threadId, message, { newTurn = false,
   await beforeSend?.(thread, client);
   await subscribe(threadId);
   const resumed = await readSendState(client, threadId);
-  if (resumed.status?.type !== "idle" || resumed.turns.some(turn => turn.status === "inProgress")) throw new Error("Task became active while resuming. Nothing was sent.");
+  if (resumed.status?.type !== "idle" || resumed.turns.some(turn => turn.status === "inProgress")) throw Object.assign(new Error("Task became active while resuming. Nothing was sent."), { code: "TASK_BUSY" });
   await beforeSend?.(resumed, client);
   const clientUserMessageId = clientMessageId;
   const accepted = await client.request("turn/start", { threadId, input, clientUserMessageId }, { mutation: true });
@@ -110,7 +110,7 @@ export async function sendAppServerMessage(threadInput, message, { dryRun = fals
   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.");
+  if (typeof message !== "string" || !message.trim()) throw Object.assign(new Error("Message must not be empty."), { code: "OPTIONS_INVALID" });
   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;

package/src/checkpoint.mjs

@@ -22,13 +22,13 @@ export async function captureInputs(roots, excludes = [], { allowMissing = false
     try { info = await lstat(file); } catch (e) { if (e.code === "ENOENT" && allowMissing) return; throw e; }
     if (info.isSymbolicLink()) {
       const target = await realpath(file), targetInfo = await lstat(target);
-      if (targetInfo.isDirectory()) throw new Error("Directory symlinks are not snapshot inputs. Specify the real directory explicitly.");
+      if (targetInfo.isDirectory()) throw Object.assign(new Error("Directory symlinks are not snapshot inputs. Specify the real directory explicitly."), { code: "OPTIONS_INVALID" });
       records.set(file, { ...await fingerprintFile(file), link: await readlink(file), mtime_ms: targetInfo.mtimeMs, ctime_ms: targetInfo.ctimeMs });
     } else if (info.isDirectory()) {
       records.set(file, { type: "directory", ref: file, mode: info.mode & 0o777 });
       for (const name of (await readdir(file)).sort()) await visit(path.join(file, name));
     } else if (info.isFile()) records.set(file, { ...await fingerprintFile(file), mtime_ms: info.mtimeMs, ctime_ms: info.ctimeMs });
-    else throw new Error("Snapshot inputs must be files or directories.");
+    else throw Object.assign(new Error("Snapshot inputs must be files or directories."), { code: "OPTIONS_INVALID" });
   }
   for (const root of roots) await visit(root);
   const files = [...records.values()].sort((a, b) => a.ref.localeCompare(b.ref));
@@ -42,18 +42,18 @@ function differences(before, after) {
 
 export async function getCheckpoint(threadInput, 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.");
+  if (!entry || entry.thread_id !== threadId || entry.id !== id) throw Object.assign(new Error("Checkpoint not found for this task."), { code: "CHECKPOINT_NOT_FOUND" });
   return entry;
 }
 
 export async function createCheckpoint(threadInput, name, { paths, excludes = [], cwd = process.cwd(), ...storage }) {
   const threadId = normalizeTaskId(threadInput);
-  if (!name?.trim() || !paths?.length) throw new Error("capture requires a name and at least one --path.");
+  if (!name?.trim() || !paths?.length) throw Object.assign(new Error("capture requires a name and at least one --path."), { code: "OPTIONS_INVALID" });
   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.");
+  if (!snapshot.files.some(f => f.type === "file")) throw Object.assign(new Error("No input files were selected."), { code: "OPTIONS_INVALID" });
   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);
@@ -115,13 +115,13 @@ function watchInputs(snapshot) {
 }
 
 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.");
+  if (!argv.length || !argv[0] || !Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 86400000) throw Object.assign(new Error("A command and timeout-ms between 0 and 86400000 are required."), { code: "OPTIONS_INVALID" });
   const threadId = normalizeTaskId(threadInput);
   return withStoreLock(`checkpoint-${id}`, async () => {
     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.");
+      if (before.digest !== entry.snapshot.digest) throw Object.assign(new Error("Inputs changed since capture. Capture a new checkpoint before running."), { code: "STALE_CHECKPOINT" });
       const run = { id: randomUUID(), argv, status: "running", started_at: new Date().toISOString() };
       entry.runs.push(run); await writeRecord("checkpoints", id, entry, storage);
       let result;
@@ -145,12 +145,12 @@ export async function runCheckpoint(threadInput, id, argv, { timeoutMs = 0, exec
 }
 
 export async function attachArtifacts(threadInput, id, refs, storage = {}) {
-  if (!refs.length) throw new Error("At least one --artifact file is required.");
+  if (!refs.length) throw Object.assign(new Error("At least one --artifact file is required."), { code: "OPTIONS_INVALID" });
   return withStoreLock(`checkpoint-${id}`, async () => {
     const verified = await verifyCheckpoint(threadInput, id, storage);
-    if (!verified.valid) throw new Error("A successful run against unchanged inputs is required before attaching artifacts.");
+    if (!verified.valid) throw Object.assign(new Error("A successful run against unchanged inputs is required before attaching artifacts."), { code: "STALE_CHECKPOINT" });
     const artifacts = await collectEvidence(refs);
-    if (artifacts.some(a => a.type !== "file")) throw new Error("Artifacts must be local files.");
+    if (artifacts.some(a => a.type !== "file")) throw Object.assign(new Error("Artifacts must be local files."), { code: "OPTIONS_INVALID" });
     const entry = await getCheckpoint(threadInput, id, storage);
     entry.artifacts.push(...artifacts.map(a => ({ ...a, run_id: entry.runs.at(-1).id, attached_at: new Date().toISOString() })));
     await writeRecord("checkpoints", id, entry, storage);