codexteer 0.16.0 → 0.18.0

package/src/cloud-observe.mjs

@@ -0,0 +1,178 @@
+import { createHash, randomUUID } from "node:crypto";
+import { cloudApi, cloudCredentials } from "./cloud-api.mjs";
+import { cloudTaskId } from "./cloud-id.mjs";
+import { readRecord, storePath, withStoreLock, writeRecord } from "./store.mjs";
+
+const failure = (code, message) => Object.assign(new Error(message), { code, execution_environment: "cloud" });
+const digest = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const validTurn = (task, value) => typeof value === "string" && value.startsWith(`${task}~`) && /^(?:usertrn|assttrn)_[A-Za-z0-9_-]{1,200}$/.test(value.slice(task.length + 1));
+export const cloudUserRevision = snapshot => digest(snapshot.turns.filter(turn => turn.role === "user").map(turn => ({ id: turn.turn_id, parent: turn.parent_turn_id, messages: turn.messages })));
+
+function texts(items) {
+  return (Array.isArray(items) ? items : []).filter(item => item?.type === "message").map(item => ({
+    role: typeof item.role === "string" ? item.role : null,
+    text: (Array.isArray(item.content) ? item.content : []).flatMap(part => typeof part === "string" ? [part]
+      : part?.content_type === "text" && typeof part.text === "string" ? [part.text] : []).join("\n"),
+  })).filter(item => item.text);
+}
+
+function publicProgress(items) {
+  return (Array.isArray(items) ? items : []).flatMap(item => {
+    const role = item?.role ?? item?.author?.role;
+    if (role !== "assistant" || ![undefined, null, "commentary"].includes(item.channel)
+      || item.type === "reasoning" || (item.recipient != null && item.recipient !== "all") || item.metadata?.is_visually_hidden_from_conversation === true
+      || (item.metadata?.reasoning_status != null && item.metadata?.is_thinking_preamble_message !== true)) return [];
+    let text;
+    if (Array.isArray(item.content)) text = texts([{ ...item, type: "message" }])[0]?.text;
+    else if (["text", "multimodal_text"].includes(item.content?.content_type) && Array.isArray(item.content.parts)) text = item.content.parts.filter(part => typeof part === "string").join("");
+    if (!text) return [];
+    return [{ ...(typeof item.id === "string" && item.id.length <= 512 && !/[\x00-\x1f]/u.test(item.id) ? { id: item.id } : {}), role: "assistant", text }];
+  });
+}
+
+function progress(turn) {
+  const items = publicProgress(turn.worklog?.messages), seen = new Set(items.flatMap(item => item.id === undefined ? [] : [item.id]));
+  const latest = new Map();
+  for (const event of [...(turn.thread_events?.events ?? []), ...(turn.app_server_events?.events ?? [])]) {
+    const item = event?.params?.item;
+    if (!["item/started", "item/completed"].includes(event?.method) || item?.type !== "agentMessage" || item.phase !== "commentary"
+      || typeof item.id !== "string" || !item.id || item.id.length > 512 || /[\x00-\x1f]/u.test(item.id) || typeof item.text !== "string" || !item.text) continue;
+    latest.set(item.id, { id: item.id, role: "assistant", text: item.text });
+  }
+  return [...items, ...[...latest.values()].filter(item => !seen.has(item.id))];
+}
+
+function commands(turn) {
+  const latest = new Map();
+  for (const event of [...(turn.thread_events?.events ?? []), ...(turn.app_server_events?.events ?? [])]) {
+    const item = event?.params?.item;
+    if (!["item/started", "item/completed"].includes(event?.method) || item?.type !== "commandExecution" || typeof item.id !== "string") continue;
+    latest.set(item.id, { id: item.id, status: typeof item.status === "string" ? item.status : "unknown",
+      command: typeof item.command === "string" ? item.command : null, output: typeof item.aggregatedOutput === "string" ? item.aggregatedOutput : null,
+      exit_code: Number.isInteger(item.exitCode) ? item.exitCode : null });
+  }
+  return [...latest.values()];
+}
+
+export async function readCloudTask(target, settings = {}, { request = cloudApi } = {}) {
+  const taskId = cloudTaskId(target);
+  if (settings.timeoutMs !== undefined && (!Number.isSafeInteger(settings.timeoutMs) || settings.timeoutMs < 1000 || settings.timeoutMs > 600000)) throw failure("CLOUD_OPTIONS_INVALID", "--timeout-ms must be 1000..600000.");
+  const timeoutMs = settings.timeoutMs ?? 120000, deadline = Date.now() + timeoutMs;
+  const details = await request(`tasks/${taskId}`, { timeoutMs, ...(settings.signal ? { signal: settings.signal } : {}) });
+  if (deadline - Date.now() < 1) throw failure("CLOUD_TIMEOUT", "Cloud history deadline expired.");
+  const history = await request(`tasks/${taskId}/turns`, { timeoutMs: deadline - Date.now(), ...(settings.signal ? { signal: settings.signal } : {}) });
+  const current = details.current_assistant_turn;
+  if (details.task?.id !== taskId || current?.role !== "assistant" || !validTurn(taskId, current?.id) || !current.id.startsWith(`${taskId}~assttrn_`) || !history.turn_mapping || typeof history.turn_mapping !== "object" || Array.isArray(history.turn_mapping)) {
+    throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud did not confirm the requested task and its turn history.");
+  }
+  if (details.task.current_turn_id !== history.current_turn_id || !history.turn_mapping[current.id]) throw failure("CLOUD_STATE_CHANGED", "Cloud changed while reading. Read again before sending.");
+  const nodes = Object.entries(history.turn_mapping);
+  if (nodes.length > 10000 || nodes.some(([id, node]) => !validTurn(taskId, id) || node?.turn?.id !== id || (node.parent != null && !validTurn(taskId, node.parent)))) {
+    throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud history contains an unrecognized turn identity.");
+  }
+  const turns = nodes.map(([id, node]) => ({ turn_id: id, parent_turn_id: node.parent ?? null,
+    role: node.turn.role, status: node.turn.turn_status ?? null, created_at: node.turn.created_at ?? null,
+    messages: texts(node.turn.input_items ?? node.turn.output_items),
+    progress: progress(node.turn),
+    commands: commands(node.turn),
+  })).sort((a, b) => (a.created_at ?? 0) - (b.created_at ?? 0) || a.turn_id.localeCompare(b.turn_id));
+  const snapshot = { task_id: taskId, turn_id: current.id, current_turn_id: history.current_turn_id, status: current.turn_status ?? "unknown",
+    title: typeof details.task.title === "string" && details.task.title.length <= 2000 ? details.task.title : null, turns };
+  return { backend: "codex-api", execution_environment: "cloud", ...snapshot,
+    history_scope: "all-returned-turns", url: `https://chatgpt.com/codex/tasks/${taskId}` };
+}
+
+export async function sendCloudTask(target, expectedTurn, prompt, settings = {}, dependencies = {}) {
+  const taskId = cloudTaskId(target);
+  if (settings.timeoutMs !== undefined && (!Number.isSafeInteger(settings.timeoutMs) || settings.timeoutMs < 1000 || settings.timeoutMs > 600000)) throw failure("CLOUD_OPTIONS_INVALID", "--timeout-ms must be 1000..600000.");
+  if (!validTurn(taskId, expectedTurn) || typeof settings.expectedUserRevision !== "string" || !/^[a-f0-9]{64}$/.test(settings.expectedUserRevision) || !["steer", "new-turn"].includes(settings.deliveryMode)) throw failure("CLOUD_OPTIONS_INVALID", "Cloud delivery requires the exact parent turn, user-input revision and delivery mode.");
+  if (typeof prompt !== "string" || !prompt.trim() || prompt.includes("\0") || Buffer.byteLength(prompt) > 1024 * 1024) throw failure("CLOUD_OPTIONS_INVALID", "A non-empty instruction of at most 1 MiB is required.");
+  const request = dependencies.request ?? cloudApi, read = dependencies.read ?? readCloudTask;
+  const write = dependencies.write ?? writeRecord, load = dependencies.load ?? readRecord, lock = dependencies.lock ?? withStoreLock;
+  // Pin one official account for the read/compare/send sequence. Never refresh
+  // or automatically retry an unknown submission against a different account.
+  const auth = dependencies.request ? null : await cloudCredentials();
+  const api = (route, options = {}) => request(route, { ...options, ...(auth ? { credentials: async () => auth } : {}) });
+  try { return await lock(`cloud-send-${taskId}`, async () => {
+    const observation = await read(taskId, { timeoutMs: settings.timeoutMs }, { request: api });
+    if (observation.turn_id !== expectedTurn || cloudUserRevision(observation) !== settings.expectedUserRevision) throw failure("CLOUD_STATE_CHANGED", "Cloud task or user input changed after observation. Read again; no message was sent.");
+    const active = ["in_progress", "pending", "queued", "running"].includes(observation.status);
+    if (settings.deliveryMode === "steer" ? !active : !["completed", "failed", "cancelled"].includes(observation.status)) {
+      throw failure(active ? "CLOUD_TASK_BUSY" : "CLOUD_TASK_IDLE", settings.deliveryMode === "steer"
+        ? "The task has no active turn. Use --new-turn to continue an idle cloud task."
+        : "A new turn requires a finished cloud turn. Nothing was sent.");
+    }
+    const previous = await load("cloud-send-heads", taskId);
+    const safelyUnsent = previous?.submission_status === "not_sent" && previous.dispatch_started === false;
+    if (previous && !safelyUnsent && (previous.submission_status !== "accepted" || previous.parent_turn_id === expectedTurn)) throw Object.assign(failure("CLOUD_DUPLICATE_SEND", "An accepted or uncertain send needs inspection before another send. Use history check <TASK> --attempt <ATTEMPT_ID>; do not resend."), { existing_attempt_id: previous.attempt_id, existing_receipt_path: previous.receipt_path });
+    const attemptId = randomUUID();
+    const receipt = { execution_environment: "cloud", backend: "codex-api", task_id: taskId, parent_turn_id: expectedTurn,
+      attempt_id: attemptId, receipt_path: storePath("cloud-messages", attemptId), user_revision: settings.expectedUserRevision,
+      prompt_sha256: createHash("sha256").update(prompt).digest("hex"), prompt_hash_encoding: "utf8", message_characters: [...prompt].length,
+      delivery_action: active ? "interrupt-and-follow-up" : "new-turn", parent_status: observation.status, submission_status: "not_sent", dry_run: !!settings.dryRun };
+    await settings.beforeSend?.(observation);
+    if (settings.dryRun) return receipt;
+    const dispatched = { ...receipt, submission_status: "dispatching" };
+    try {
+      await write("cloud-messages", attemptId, receipt);
+      // Finish receipt persistence before reserving the head. There must be no
+      // fallible persistence between the reservation and the single POST.
+      await write("cloud-messages", attemptId, dispatched);
+      await write("cloud-send-heads", taskId, dispatched);
+    } catch {
+      const unsent = { ...receipt, dispatch_started: false, error_code: "CLOUD_PERSISTENCE_FAILED" };
+      try { await write("cloud-send-heads", taskId, previous ?? unsent); }
+      catch { unsent.reservation_cleanup_required = true; unsent.receipt_update_required = true; }
+      try { await write("cloud-messages", attemptId, unsent); }
+      catch { unsent.receipt_update_required = true; }
+      throw Object.assign(failure("CLOUD_PERSISTENCE_FAILED", "Cloud send records could not be prepared. No request was sent. Inspect the receipt and reservation before an explicit retry."), unsent, { uncertain: false });
+    }
+    let response;
+    try {
+      response = await api("tasks", { timeoutMs: settings.timeoutMs, body: {
+        follow_up: { task_id: taskId, turn_id: expectedTurn, environment_mode: "code" },
+        input_items: [{ type: "message", role: "user", content: [{ content_type: "text", text: prompt }] }],
+      } });
+      if ((response.task?.id ?? response.id) !== taskId) throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud did not confirm the same task after follow-up.");
+      receipt.submission_status = "accepted";
+    } catch (error) {
+      receipt.submission_status = "unknown";
+      receipt.error_code = error.code ?? "CLOUD_SEND_FAILED";
+      try { await write("cloud-messages", attemptId, receipt); } catch { receipt.receipt_update_required = true; }
+      throw Object.assign(failure(receipt.error_code, "Cloud follow-up outcome is unknown. Read this task and inspect the receipt before retrying; no automatic retry was made."), receipt, { uncertain: true });
+    }
+    try { await write("cloud-messages", attemptId, receipt); await write("cloud-send-heads", taskId, receipt); } catch { receipt.receipt_update_required = true; }
+    return receipt;
+  }); } finally { if (auth) auth.token = ""; }
+}
+
+export async function cloudSendReceipt(attemptId, { load = readRecord, taskId } = {}) {
+  if (typeof attemptId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(attemptId)) throw failure("CLOUD_OPTIONS_INVALID", "A cloud send attempt UUID is required.");
+  const receipt = await load("cloud-messages", attemptId);
+  if (!receipt) throw failure("CLOUD_RECEIPT_NOT_FOUND", "Cloud send receipt was not found.");
+  if (taskId !== undefined && cloudTaskId(receipt.task_id) !== cloudTaskId(taskId)) throw failure("CLOUD_TARGET_CONFLICT", "The send attempt belongs to another cloud task.");
+  return receipt;
+}
+
+export async function reconcileCloudSend(attemptId, { read = readCloudTask, load = readRecord, write = writeRecord, lock = withStoreLock, taskId: expectedTask, expectedPromptSha256, expectedParentTurnId } = {}) {
+  const receipt = await cloudSendReceipt(attemptId, { load, taskId: expectedTask });
+  const taskId = cloudTaskId(receipt.task_id);
+  if ((expectedPromptSha256 !== undefined && receipt.prompt_sha256 !== expectedPromptSha256)
+    || (expectedParentTurnId !== undefined && receipt.parent_turn_id !== expectedParentTurnId)) {
+    return { ...receipt, delivery_verification: "conflict", retry_safe: false };
+  }
+  return lock(`cloud-send-${taskId}`, async () => {
+    if (receipt.submission_status === "not_sent" && receipt.dispatch_started === false) {
+      if ((await load("cloud-send-heads", taskId))?.attempt_id === attemptId) await write("cloud-send-heads", taskId, receipt);
+      return { ...receipt, delivery_verification: "not_sent", retry_safe: true, reservation_cleanup_required: false };
+    }
+    const snapshot = await read(taskId);
+    const matches = snapshot.turns.filter(turn => turn.role === "user" && turn.parent_turn_id === receipt.parent_turn_id
+      && turn.messages.some(message => createHash("sha256").update(message.text).digest("hex") === receipt.prompt_sha256));
+    if (matches.length !== 1) return { ...receipt, delivery_verification: "not_observed", retry_safe: false };
+    Object.assign(receipt, { submission_status: "accepted", delivery_verification: "stored", user_turn_id: matches[0].turn_id });
+    await write("cloud-messages", attemptId, receipt);
+    if ((await load("cloud-send-heads", taskId))?.attempt_id === attemptId) await write("cloud-send-heads", taskId, receipt);
+    return receipt;
+  });
+}

package/src/cloud-send.mjs

@@ -0,0 +1,33 @@
+import { cloudTaskId } from "./cloud-id.mjs";
+import { cloudThread, CloudReadClient } from "./cloud-connection.mjs";
+import { readCloudTask, sendCloudTask, cloudUserRevision } from "./cloud-observe.mjs";
+
+export async function sendCloudInput(target, message, options = {}, dependencies = {}) {
+  const taskId = cloudTaskId(target), read = dependencies.read ?? readCloudTask, send = dependencies.send ?? sendCloudTask;
+  if (typeof message !== "string" || !message.trim() || message.includes("\0") || Buffer.byteLength(message) > 1024 * 1024) throw Object.assign(new Error("A non-empty cloud instruction of at most 1 MiB is required."), { code: "CLOUD_OPTIONS_INVALID" });
+  if (options.dryRun) return { thread_id: taskId, task_id: taskId, backend: "codex-api", execution_environment: "cloud", delivery_action: options.newTurn ? "new-turn" : "interrupt-and-follow-up",
+    message_characters: [...message].length, dry_run: true, sent: false, delivery_status: "not_sent", freshness_checked: false };
+  const snapshot = await read(taskId);
+  const active = cloudThread(snapshot).turns.filter(turn => turn.status === "inProgress");
+  if (options.newTurn ? active.length > 0 : active.length !== 1 || active[0]?.id !== snapshot.turn_id) {
+    throw Object.assign(new Error(options.newTurn ? "--new-turn requires an idle cloud task." : "The cloud task has no unambiguous selected active turn. Read it again before sending."), { code: options.newTurn ? "CLOUD_TASK_BUSY" : "CLOUD_TURN_AMBIGUOUS" });
+  }
+  const client = new CloudReadClient({ read });
+  try {
+    const receipt = await send(taskId, snapshot.turn_id, message, {
+      dryRun: !!options.dryRun, deliveryMode: options.newTurn ? "new-turn" : "steer",
+      expectedUserRevision: cloudUserRevision(snapshot),
+      beforeSend: current => options.beforeSend?.(cloudThread(current), client),
+    });
+    return { thread_id: taskId, task_id: taskId, backend: "codex-api", execution_environment: "cloud",
+      message_characters: [...message].length, dry_run: !!options.dryRun, sent: !options.dryRun,
+      delivery_status: options.dryRun ? "not_sent" : "accepted", delivery_action: receipt.delivery_action,
+      cloud_attempt_id: receipt.attempt_id, cloud_parent_turn_id: receipt.parent_turn_id, client_message_id: options.clientMessageId,
+      turn_id: null, receipt_path: receipt.receipt_path, receipt_update_required: receipt.receipt_update_required,
+      turn_identity: "follow-up; read/history-check confirms the new turn", freshness_atomic: false };
+  } catch (error) {
+    error.cloud_attempt_id = error.attempt_id; error.cloud_parent_turn_id = error.parent_turn_id;
+    error.delivery_status = error.uncertain ? "unknown" : "not_sent"; error.sent = error.uncertain ? null : false;
+    throw error;
+  } finally { client.close(); }
+}

package/src/cloud.mjs

@@ -0,0 +1,172 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { readRecord, storePath, writeRecord } from "./store.mjs";
+import { cloudApi } from "./cloud-api.mjs";
+import { cloudTaskId } from "./cloud-id.mjs";
+
+const failure = (message, code = "CLOUD_OPTIONS_INVALID") => Object.assign(new Error(message), { code });
+const taskUrl = id => `https://chatgpt.com/codex/tasks/${id}`;
+
+function options(settings = {}) {
+  const timeoutMs = settings.timeoutMs ?? 120000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000) throw failure("--timeout-ms must be 1000..600000.");
+  return { timeoutMs };
+}
+
+// No shell, authentication parsing, automatic installation, or Desktop fallback.
+// Prompt input goes through stdin, never the child argv or an on-disk prompt file.
+export async function runCloudCli(args, { input = "", timeoutMs = 120000, maxBytes = 16 * 1024 * 1024 } = {}) {
+  let directory;
+  try { directory = await mkdtemp(path.join(os.tmpdir(), "codexteer-cloud-cli-")); }
+  catch { return { started: false, launchError: "PRIVATE_DIRECTORY_UNAVAILABLE" }; }
+  // The official cloud CLI can write error.log in cwd, including backend data.
+  // Do not place it in a user's checkout or package. Remove the private cwd.
+  const environment = { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0", CLICOLOR: "0", TERM: "dumb" };
+  delete environment.CODEX_STARTING_DIFF;
+  try { return await new Promise(resolve => {
+    let child, started = false, stdout = "", bytes = 0, timedOut = false, overflow = false, ioError = false, launchError, killTimer;
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"], handlers = new Map();
+    try {
+      child = spawn("codex", ["cloud", ...args], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true, cwd: directory, env: environment });
+    } catch (error) { resolve({ started, launchError: error.code }); return; }
+    child.once("spawn", () => { started = true; });
+    child.once("error", error => { launchError = error.code ?? "SPAWN_ERROR"; });
+    const stop = signal => { child.kill(signal); killTimer ??= setTimeout(() => child.kill("SIGKILL"), 500); };
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", chunk => { bytes += Buffer.byteLength(chunk); if (bytes <= maxBytes) stdout += chunk; else { overflow = true; stop(); } });
+    // Drain but never expose or persist raw diagnostics (which may contain secrets).
+    child.stderr.on("data", chunk => { bytes += chunk.length; if (bytes > maxBytes) { overflow = true; stop(); } });
+    child.stdin.on("error", error => { if (error.code !== "EPIPE") ioError = true; });
+    const timer = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+    for (const signal of signals) {
+      const handler = () => stop(signal); handlers.set(signal, handler); process.once(signal, handler);
+    }
+    child.once("close", (exitCode, signal) => {
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      for (const [name, handler] of handlers) process.removeListener(name, handler);
+      resolve({ started, stdout, exitCode, signal, timedOut, overflow, ioError, launchError });
+    });
+    child.stdin.end(input);
+  }); } finally { await rm(directory, { recursive: true, force: true }); }
+}
+
+function completed(result) { return !result.launchError && !result.signal && !result.timedOut && !result.overflow && !result.ioError; }
+function cliFailure(result) {
+  const code = !result.started && result.launchError ? "CLOUD_CLI_UNAVAILABLE" : result.timedOut ? "CLOUD_TIMEOUT" : result.overflow ? "CLOUD_OUTPUT_LIMIT" : "CLOUD_CLI_FAILED";
+  return Object.assign(failure(code === "CLOUD_CLI_UNAVAILABLE" ? "Cannot start codex from PATH. Install the official Codex CLI; no fallback was attempted."
+    : "Codex Cloud command failed. Check the official CLI login and environment access. Raw diagnostics are omitted to avoid exposing private data.", code),
+  { cli_exit_code: result.exitCode, cli_signal: result.signal });
+}
+
+async function preflight(action, run) {
+  const result = await run([action, "--help"], { timeoutMs: 10000 });
+  if (!completed(result) || result.exitCode !== 0) throw cliFailure(result);
+  const required = action === "exec" ? ["codex cloud exec", "--env", "--branch", "--attempts"] : [`codex cloud ${action}`, ...(action === "diff" ? ["--attempt"] : [])];
+  if (!required.every(text => result.stdout.includes(text))) throw failure("The installed Codex CLI does not expose the required cloud command. No task was submitted.", "CLOUD_CLI_UNSUPPORTED");
+  // '-' must mean stdin, not a literal initial instruction. Older, unverified
+  // CLI versions are refused before a mutation even if their flags look alike.
+  const version = await run(["--version"], { timeoutMs: 10000 });
+  if (!completed(version) || version.exitCode !== 0) throw cliFailure(version);
+  const match = version.stdout?.trim().match(/^codex-cli-cloud (\d+)\.(\d+)\.(\d+)(?:[-+][\w.-]+)?$/);
+  if (!match || !(Number(match[1]) > 0 || Number(match[2]) > 157 || (Number(match[2]) === 157 && Number(match[3]) >= 1))) throw failure("Codex Cloud requires the official CLI 0.157.1 or newer with verified stdin semantics. No task was submitted.", "CLOUD_CLI_UNSUPPORTED");
+  return match[0];
+}
+
+export async function createCloudTask(environment, branch, prompt, settings = {}, dependencies = {}) {
+  const limits = options(settings);
+  if (typeof environment !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/.test(environment)) throw failure("--env requires a cloud environment ID or simple unique label.");
+  // Require an explicit Git branch instead of inheriting the active local branch.
+  if (typeof branch !== "string" || !branch || branch.length > 255 || branch.startsWith("-") || branch.startsWith("/") || branch.endsWith("/")
+    || /[\s\x00-\x1f\x7f~^:?*\[\\]/u.test(branch) || branch.includes("..") || branch.includes("@{") || branch.includes("//")
+    || branch.split("/").some(part => part.startsWith(".") || part.endsWith(".lock") || part.endsWith("."))) throw failure("--branch requires an explicit valid Git branch name.");
+  if (typeof prompt !== "string" || !prompt.trim() || prompt.includes("\0") || Buffer.byteLength(prompt) > 1024 * 1024) throw failure("A non-empty initial instruction of at most 1 MiB is required.");
+  const run = dependencies.run ?? runCloudCli, write = dependencies.write ?? writeRecord;
+  const attemptId = randomUUID();
+  const receipt = { schema: 1, backend: "codex-cli", execution_environment: "cloud", attempt_id: attemptId,
+    environment_selector: environment, branch, creation_status: "not_created", submission_status: "not_sent",
+    prompt_sha256: createHash("sha256").update(prompt).digest("hex"), message_characters: [...prompt].length, dry_run: !!settings.dryRun };
+  if (settings.dryRun) return receipt;
+  receipt.cli_version = await preflight("exec", run);
+  receipt.receipt_path = storePath("cloud-creations", attemptId);
+  await write("cloud-creations", attemptId, receipt);
+  let dispatched = false;
+  try {
+    await write("cloud-creations", attemptId, { ...receipt, creation_status: "dispatching", submission_status: "dispatching" });
+    dispatched = true;
+    const result = await run(["exec", "--env", environment, "--branch", branch, "--attempts", "1", "-"], { ...limits, input: prompt });
+    if (!result.started && result.launchError) { dispatched = false; throw cliFailure(result); }
+    // The official CLI prints exactly the created task URL. No inferred IDs.
+    let id;
+    const acknowledgement = result.stdout?.trim();
+    if (typeof acknowledgement === "string" && /^https:\/\/chatgpt\.com\/codex\/tasks\/task_[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/.test(acknowledgement)) id = cloudTaskId(acknowledgement);
+    if (id) Object.assign(receipt, { task_id: id, url: taskUrl(id), creation_status: "created" });
+    if (!completed(result) || result.exitCode !== 0) throw cliFailure(result);
+    if (!id) throw failure("No unique cloud task ID was confirmed. Inspect the receipt and cloud task list; do not submit again automatically.", "CLOUD_CREATION_UNKNOWN");
+    receipt.submission_status = "accepted";
+    try { await write("cloud-creations", attemptId, receipt); } catch { receipt.receipt_update_required = true; }
+    return receipt;
+  } catch (error) {
+    Object.assign(receipt, { creation_status: receipt.task_id ? "created" : dispatched ? "unknown" : "not_created",
+      submission_status: dispatched ? "unknown" : "not_sent", error_code: error.code ?? "CLOUD_CLI_FAILED" });
+    try { await write("cloud-creations", attemptId, receipt); } catch { receipt.receipt_update_required = true; }
+    // Never propagate a child-process Error: its message can embed the prompt.
+    throw Object.assign(failure("Cloud task submission was not fully confirmed. Inspect the receipt and existing tasks before retrying; no automatic retry was made.", receipt.error_code),
+      { ...receipt, uncertain: dispatched, cli_exit_code: error.cli_exit_code, cli_signal: error.cli_signal });
+  }
+}
+
+export async function cloudTaskDiff(target, settings = {}, { run = runCloudCli, request = cloudApi } = {}) {
+  const taskId = cloudTaskId(target), limits = options(settings);
+  if (settings.attempt !== undefined && (!Number.isInteger(settings.attempt) || settings.attempt < 1 || settings.attempt > 4)) throw failure("--attempt must be 1..4.");
+  await preflight("diff", run);
+  const result = await run(["diff", taskId, ...(settings.attempt === undefined ? [] : ["--attempt", String(settings.attempt)])], limits);
+  if (completed(result) && result.exitCode === 1 && settings.attempt === undefined) {
+    // A finished task may have commands/files but no recorded patch. Verify
+    // this through the same task's API; never turn stderr into a diff or infer
+    // that no files changed from the absence of a server-provided patch.
+    const details = await request(`tasks/${taskId}`, limits);
+    const current = details.current_assistant_turn;
+    if (details.task?.id === taskId && current?.role === "assistant" && ["completed", "failed", "cancelled"].includes(current.turn_status)
+      && details.current_diff_task_turn == null && Array.isArray(current.output_items) && !current.output_items.some(item => ["output_diff", "pr"].includes(item?.type))) {
+      return { backend: "codex-api", execution_environment: "cloud", task_id: taskId, url: taskUrl(taskId), attempt: null,
+        attempt_selection: "official-cli-default", diff: null, diff_available: false, reason: "no-server-recorded-patch", local_changes: "unknown" };
+    }
+  }
+  if (!completed(result) || result.exitCode !== 0) throw cliFailure(result);
+  return { backend: "codex-cli", execution_environment: "cloud", task_id: taskId, url: taskUrl(taskId), attempt: settings.attempt ?? null,
+    attempt_selection: settings.attempt === undefined ? "official-cli-default" : "explicit", diff: result.stdout, diff_available: true };
+}
+
+export async function cloudCreationReceipt(attemptId) {
+  if (typeof attemptId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(attemptId)) throw failure("A cloud creation attempt UUID is required.");
+  const receipt = await readRecord("cloud-creations", attemptId);
+  if (!receipt) throw failure("Cloud creation receipt was not found.", "CLOUD_RECEIPT_NOT_FOUND");
+  return receipt;
+}
+
+export async function listCloudTasks({ limit = 20, cursor, environment } = {}, { run = runCloudCli } = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500 || (cursor !== undefined && (typeof cursor !== "string" || !cursor || cursor.length > 4096 || /[\x00-\x1f]/u.test(cursor)))
+    || (environment !== undefined && (typeof environment !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(environment)))) throw failure("Invalid cloud task-list limit, cursor, or environment.");
+  await preflight("list", run);
+  const collected = new Map(), seen = new Set(); let next = cursor;
+  for (let page = 0; page < 100; page++) {
+    const size = Math.min(20, limit - collected.size);
+    const result = await run(["list", "--json", "--limit", String(size), ...(next ? ["--cursor", next] : []), ...(environment ? ["--env", environment] : [])]);
+    if (!completed(result) || result.exitCode !== 0) throw cliFailure(result);
+    let data; try { data = JSON.parse(result.stdout); } catch { throw failure("Invalid official cloud task list.", "CLOUD_PROTOCOL_UNVERIFIED"); }
+    if (!Array.isArray(data.tasks) || data.tasks.length > size || (data.cursor != null && (typeof data.cursor !== "string" || !data.cursor || data.cursor.length > 4096 || /[\x00-\x1f]/u.test(data.cursor) || seen.has(data.cursor)))) throw failure("Invalid official cloud task list.", "CLOUD_PROTOCOL_UNVERIFIED");
+    for (const task of data.tasks) {
+      const id = cloudTaskId(task.id);
+      collected.set(id, { thread_id: id, task_id: id, title: typeof task.title === "string" ? task.title : null,
+        status: typeof task.status === "string" ? task.status : "unknown", updated_at: typeof task.updated_at === "string" || typeof task.updated_at === "number" ? task.updated_at : null, execution_environment: "cloud", url: taskUrl(id) });
+    }
+    next = data.cursor ?? null;
+    if (!next || collected.size >= limit) return { threads: [...collected.values()], count: collected.size, cursor: next, has_more: !!next, execution_environment: "cloud" };
+    seen.add(next);
+  }
+  throw failure("Cloud task pagination exceeded its safety limit.", "CLOUD_PROTOCOL_UNVERIFIED");
+}

package/src/connection.mjs

@@ -1,12 +1,18 @@
+import { desktopCloudConnection } from "./desktop-cloud-api.mjs";
+import { cloudConnection } from "./cloud-connection.mjs";
 import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 import { codexHome } from "./runtime.mjs";
 import { RpcClient } from "./rpc.mjs";
+import { inspectAppServerSocket } from "./socket-endpoint.mjs";
+import { targetHost, remoteTransport, isControlTransport } from "./target.mjs";
+import { remoteObservationConnection } from "./remote.mjs";
+import { remoteControlConnection } from "./remote-control.mjs";
 
 const failure = (message, code) => Object.assign(new Error(message), { code });
 const reads = new Set(["thread/loaded/list", "thread/read", "thread/turns/list", "thread/items/list"]);
 export function connectionMode(value = "shared") {
-  if (!["shared", "desktop"].includes(value)) throw new Error("--connection must be shared or desktop.");
+  if (!["shared", "desktop", "cloud", "desktop-cloud"].includes(value)) throw new Error("--connection must be shared, desktop, cloud, or desktop-cloud.");
   return value;
 }
 export function desktopReadOnly() {
@@ -16,16 +22,22 @@ export function desktopReadOnly() {
 async function identity(home) {
   const directory = path.join(home, "app-server-control"), socket = path.join(directory, "app-server-control.sock");
   const fingerprint = [];
-  for (const [file, type] of [[home, "home"], [directory, "directory"], [socket, "socket"]]) {
+  for (const [file, type] of [[home, "home"], [directory, "directory"]]) {
     const info = await lstat(file);
     if (info.uid !== process.getuid() || info.isSymbolicLink() || (info.mode & (type === "home" ? 0o022 : 0o077)) !== 0
-      || (type === "socket" ? !info.isSocket() : !info.isDirectory())) {
+      || !info.isDirectory()) {
       throw failure("Desktop control endpoint has unsafe ownership, permissions, or file type.", "DESKTOP_CONNECTION_UNSAFE");
     }
     // Home directory timestamps change for unrelated profile activity.
-    fingerprint.push([info.dev, info.ino, type === "socket" ? info.ctimeMs : null]);
+    fingerprint.push([info.dev, info.ino]);
   }
-  return { home, directory, socket, fingerprint: JSON.stringify(fingerprint) };
+  let endpoint;
+  try { endpoint = await inspectAppServerSocket(socket); }
+  catch (error) {
+    if (error.code === "SOCKET_UNSAFE") throw failure(error.message, "DESKTOP_CONNECTION_UNSAFE");
+    throw error;
+  }
+  return { home, directory, socket: endpoint.socket, fingerprint: JSON.stringify([...fingerprint, ...endpoint.fingerprint]) };
 }
 
 export async function discoverDesktopRuntime(home = codexHome()) {
@@ -89,7 +101,13 @@ export async function connectDesktop(paths, options, connect = RpcClient.connect
 // Each operation owns its discovery result. No implicit fallback to another
 // profile, daemon, or wrapper, including after connection failures.
 export function observationConnection(mode) {
+  if (targetHost() !== "local") {
+    if (connectionMode(mode) !== "shared") throw failure("Remote observation uses the selected Desktop native host route and cannot use --connection desktop.", "HOST_CONNECTION_MISMATCH");
+    return isControlTransport() ? remoteControlConnection() : remoteObservationConnection();
+  }
   if (connectionMode(mode) === "shared") return {};
+  if (mode === "desktop-cloud") return desktopCloudConnection();
+  if (mode === "cloud") return cloudConnection();
   let selected;
   return {
     async discover(home) {

package/src/creation-verification.mjs

@@ -0,0 +1,36 @@
+import { nativeToolJson } from "./native-rpc.mjs";
+
+export function validateMembershipCatalog(catalog) {
+  const schema = catalog?.tools?.find(tool => tool.name === "list_threads" && tool.namespace === "codex_app")?.inputSchema;
+  const limit = schema?.properties?.limit;
+  if (schema?.type !== "object" || !["number", "integer"].includes(limit?.type)
+    || (limit.minimum ?? 1) > 50 || (limit.maximum ?? 50) < 50) {
+    throw Object.assign(new Error("Desktop native tools do not expose the membership snapshot schema."), { code: "NATIVE_CREATION_UNSUPPORTED" });
+  }
+  return schema;
+}
+
+// The persisted legacy assignment map is not Desktop's live membership view.
+// Use the same native projection as the sidebar, and fail closed if the task
+// is outside this bounded snapshot. Canonical membership is checked separately.
+export async function desktopMembership(native, endpoint, threadId, projectId, context, options) {
+  const snapshot = nativeToolJson(await native(endpoint, "list_threads", { limit: 50 }, context, options));
+  if (!Array.isArray(snapshot.threads) || !Array.isArray(snapshot.pinnedThreads)) {
+    throw Object.assign(new Error("Invalid Desktop membership snapshot."), { code: "NATIVE_PROTOCOL_ERROR" });
+  }
+  const matches = [...snapshot.pinnedThreads, ...snapshot.threads].filter(thread => thread?.id === threadId);
+  return matches.length === 1 && matches[0].kind === "codex" && matches[0].hostId === "local" && matches[0].projectId === projectId;
+}
+
+export function initialInstructionText(history, sourceId) {
+  const item = history.turns?.[0]?.items?.find(item => item.type === "userMessage"
+    || (item.type === "functionCallOutput" && item.namespace === "codex_app" && item.name === "create_thread"));
+  if (item?.type === "userMessage") return item.content?.filter(part => part.type === "text").map(part => part.text).join("\n");
+  if (typeof sourceId !== "string" || typeof item?.output !== "string") return undefined;
+  const prefix = `<codex_delegation>\n  <source_thread_id>${sourceId}</source_thread_id>\n  <input>`, suffix = "</input>\n</codex_delegation>";
+  return item.output.startsWith(prefix) && item.output.endsWith(suffix) ? item.output.slice(prefix.length, -suffix.length) : undefined;
+}
+
+export function initialInstructionMatches(history, prompt, sourceId) {
+  return initialInstructionText(history, sourceId) === prompt;
+}

package/src/desktop-cloud-api.mjs

@@ -0,0 +1,119 @@
+import WebSocket from "ws";
+import { cloudCredentials } from "./cloud-api.mjs";
+import { RpcClient, RpcFailure } from "./rpc.mjs";
+import { VERSION } from "./version.mjs";
+import { codexHome } from "./runtime.mjs";
+import { desktopCloudId, desktopCloudUuid } from "./desktop-cloud-id.mjs";
+const origin = "https://codex-cloud-backend.chatgpt.com", limit = 16 * 1024 * 1024;
+const failure = (message, code = "DESKTOP_CLOUD_PROTOCOL_ERROR") => Object.assign(new Error(message), { code });
+const headers = auth => ({ "ChatGPT-Account-ID": auth.accountId, "X-OpenAI-Product-Sku": "codex" });
+export async function desktopCloudGet(route, { signal, timeoutMs = 30000 } = {}, { credentials = cloudCredentials, fetchRequest = fetch } = {}) {
+  const url = new URL(route, origin);
+  if (!route.startsWith("/v1/environment-configs?") || url.pathname !== "/v1/environment-configs" || url.origin !== origin) throw failure("Invalid Desktop Cloud catalog route.");
+  const controller = new AbortController(), timer = setTimeout(() => controller.abort(), timeoutMs);
+  const cancel = () => controller.abort(); signal?.addEventListener("abort", cancel, { once: true }); if (signal?.aborted) cancel();
+  const combined = controller.signal;
+  let auth;
+  try {
+    auth = await credentials({ signal: combined, timeoutMs });
+    const response = await fetchRequest(url, { method: "GET", redirect: "error", signal: combined, headers: { ...headers(auth), Authorization: `Bearer ${auth.token}`, Accept: "application/json" } });
+    if (!response.ok) { await response.body?.cancel(); throw failure(`Desktop Cloud catalog failed (HTTP ${response.status}).`, response.status === 401 ? "CLOUD_LOGIN_REQUIRED" : "DESKTOP_CLOUD_HTTP_FAILED"); }
+    const chunks = []; let size = 0;
+    for await (const part of response.body) { size += part.length; if (size > limit) throw failure("Desktop Cloud catalog exceeded its receive limit."); chunks.push(part); }
+    try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { throw failure("Desktop Cloud returned invalid catalog JSON."); }
+  } catch (error) {
+    if (/^(DESKTOP_CLOUD_|CLOUD_)/.test(error.code ?? "")) throw error;
+    throw failure("Desktop Cloud catalog did not complete.", signal?.aborted ? "CANCELLED" : controller.signal.aborted ? "TIMEOUT" : "CONNECTION_FAILED");
+  } finally { clearTimeout(timer); signal?.removeEventListener("abort", cancel); if (auth) auth.token = ""; }
+}
+export function configId(value) {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_~-]{0,399}$/.test(value)) throw failure("Invalid environment configuration ID.");
+  return value;
+}
+export async function desktopCloudEnvironments(options = {}, { get = desktopCloudGet } = {}) {
+  const rows = new Map();
+  for (const scope of ["user", "workspace"]) {
+    let cursor; const seen = new Set();
+    for (let page = 0; page < 100; page++) {
+      const query = new URLSearchParams({ scope, limit: "100", omitDraft: "true", view: "picker", ...(cursor ? { cursor } : {}) });
+      const data = await get(`/v1/environment-configs?${query}`, options);
+      if (!Array.isArray(data?.data)) throw failure("Invalid Desktop Cloud environment inventory.");
+      for (const row of data.data) {
+        const id = configId(row?.id);
+        if (typeof row.name !== "string" || !row.name.trim() || row.name.length > 1000) throw failure("Invalid environment name.");
+        if (rows.has(id) && rows.get(id).name !== row.name) throw failure("Conflicting environment entries.");
+        rows.set(id, { id, name: row.name, scope, repository_ids: Array.isArray(row.repository_ids) ? row.repository_ids.filter(x => typeof x === "string") : [] });
+      }
+      cursor = data.next_cursor; if (cursor == null) break;
+      if (typeof cursor !== "string" || !cursor || seen.has(cursor) || page === 99) throw failure("Invalid environment pagination.");
+      seen.add(cursor);
+    }
+  }
+  return { environments: [...rows.values()], source: "desktop-cloud-configurations", execution_environment: "cloud", connection_mode: "desktop-cloud" };
+}
+export async function connectDesktopCloud(options = {}, { credentials = cloudCredentials, Socket = WebSocket } = {}) {
+  const timeoutMs = options.timeoutMs ?? 30000; let auth, socket, client;
+  try {
+    auth = await credentials({ timeoutMs, signal: options.signal });
+    if (options.signal?.aborted) throw failure("Connection cancelled.", "CANCELLED");
+    socket = new Socket("wss://codex-cloud-backend.chatgpt.com/", ["codex-app-server", "codex-client.desktop", `openai-bearer.${auth.token}`], {
+      headers: headers(auth), followRedirects: false, perMessageDeflate: false, maxPayload: limit, handshakeTimeout: timeoutMs,
+    });
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const cancel = () => finish(failure("Desktop Cloud connection cancelled.", "CANCELLED"));
+      const timer = setTimeout(() => finish(failure("Desktop Cloud connection timed out.", "TIMEOUT")), timeoutMs);
+      const finish = error => { if (settled) return; settled = true; clearTimeout(timer); options.signal?.removeEventListener("abort", cancel); error ? reject(error) : resolve(); };
+      socket.on("error", () => finish(failure("Desktop Cloud connection failed.", "CONNECTION_FAILED")));
+      socket.once("close", () => finish(failure("Desktop Cloud connection closed.", "CONNECTION_FAILED")));
+      socket.once("open", () => finish()); options.signal?.addEventListener("abort", cancel, { once: true }); if (options.signal?.aborted) cancel();
+    });
+    client = new RpcClient(socket, { timeoutMs });
+    const cancelInitialization = () => client.abort("Desktop Cloud initialization cancelled.", "CANCELLED");
+    options.signal?.addEventListener("abort", cancelInitialization, { once: true });
+    if (options.signal?.aborted) cancelInitialization();
+    try { await client.request("initialize", { clientInfo: { name: "codexteer", version: VERSION }, capabilities: { experimentalApi: true } }); } finally { options.signal?.removeEventListener("abort", cancelInitialization); }
+    client.notify("initialized", {});
+    return new DesktopCloudClient(client);
+  } catch (error) {
+    client?.close(); socket?.terminate();
+    // ws errors can quote the bearer subprotocol; never expose arbitrary errors.
+    if (error instanceof RpcFailure || ["TIMEOUT", "CANCELLED", "CONNECTION_FAILED"].includes(error.code) || /^CLOUD_/.test(error.code ?? "")) throw error;
+    throw failure("Could not initialize Desktop Cloud.", "CONNECTION_FAILED");
+  } finally { if (auth) auth.token = ""; }
+}
+export class DesktopCloudClient {
+  constructor(client) { this.client = client; }
+  close() { this.client.close(); }
+  async history(threadId) {
+    const turns = [], seen = new Set(); let cursor, bytes = 0;
+    for (let page = 0; page < 100; page++) {
+      const data = await this.client.request("thread/turns/list", { threadId, itemsView: "full", sortDirection: "asc", limit: 100, ...(cursor ? { cursor } : {}) });
+      if (!Array.isArray(data?.data) || data.data.some(turn => typeof turn.id !== "string" || !Array.isArray(turn.items) || turn.itemsView !== "full") || new Set([...turns, ...data.data].map(turn => turn.id)).size !== turns.length + data.data.length) throw failure("Invalid complete Cloud history.");
+      bytes += Buffer.byteLength(JSON.stringify(data.data)); if (bytes > 32 * 1024 * 1024) throw failure("Complete Cloud history exceeded its memory budget.");
+      turns.push(...data.data); cursor = data.nextCursor;
+      if (cursor == null) return turns;
+      if (typeof cursor !== "string" || !cursor || seen.has(cursor) || page === 99) throw failure("Cloud history exceeded its pagination limit.");
+      seen.add(cursor);
+    }
+  }
+  async request(method, params = {}, options = {}) {
+    if (!["thread/read", "thread/turns/list", "thread/items/list", "thread/list", "model/list", "thread/start", "thread/name/set", "turn/start", "turn/steer"].includes(method)) throw failure("Unsupported Desktop Cloud operation.", "CAPABILITY_UNSUPPORTED");
+    const input = { ...params }; if (input.threadId) input.threadId = desktopCloudUuid(input.threadId); if (method === "thread/read") delete input.includeTurns;
+    try {
+      const result = await this.client.request(method, input, options);
+      if (result?.thread) {
+        if (params.threadId && result.thread.id !== desktopCloudUuid(params.threadId)) throw new RpcFailure("Desktop Cloud returned another task.", { code: "PROTOCOL_ERROR", uncertain: !!options.mutation });
+        return { ...result, thread: { ...result.thread, id: desktopCloudId(`durable_${result.thread.id}`), historyMode: "aggregate", turns: method === "thread/read" && params.includeTurns ? await this.history(input.threadId) : [] } };
+      }
+      return result;
+    } catch (error) { if (options.mutation && Number.isSafeInteger(error.rpcCode) && ![-32601, -32602].includes(error.rpcCode)) error.uncertain = true; throw error; }
+  }
+}
+export function desktopCloudConnection() {
+  return {
+    async discover(home = codexHome()) { return { paths: { home, socket: "desktop-cloud" }, state: { codex_home: home, codex_steer_protocol: 1,
+      codex_steer_capabilities: { thread_read: [1], history_pagination: [1], turn_steer: [], turn_start: [], desktop_subscribe: [] } } }; },
+    async connect(endpoint, options) { if (endpoint !== "desktop-cloud") throw failure("Invalid Desktop Cloud endpoint."); return connectDesktopCloud(options); },
+  };
+}