codexteer 0.17.0 → 0.18.0

package/src/cli.mjs

@@ -1,8 +1,10 @@
 import { readFileSync } from "node:fs";
 import { desktopDoctor, inspectDesktopUi, openDesktopThread, sendDesktopMessage } from "./desktop.mjs";
-import { normalizeThreadId, threadDeepLink } from "./thread-id.mjs";
+import { normalizeThreadId, threadDeepLink, parseThreadTarget } from "./thread-id.mjs";
+import { targetHost, targetContext, withTarget, validateHostId, hostFields, remoteReadOnly, remoteTransport, validateRemoteTransport, isControlTransport } from "./target.mjs";
 import { listLocalThreads } from "./thread-store.mjs";
 import { sendTrackedMessage, listMessages, getMessage, messageSummary, reconcileMessages, markMessage, listInstructions } from "./journal.mjs";
+import { launchDesktopUpdate, desktopUpdateStatus } from "./update.mjs";
 import { appServerDoctor, startDesktop } from "./launcher.mjs";
 import { VERSION, helpData, renderHelp } from "./help.mjs";
 import { observeThread, printObservation } from "./observe.mjs";
@@ -12,33 +14,65 @@ import { createCheckpoint, listCheckpoints, getCheckpoint, checkpointSummary, ve
 import { acquireResource, resourceStatus, renewResource, releaseResource, listResources, runWithResource } from "./resource.mjs";
 import { playSendSound } from "./sound.mjs";
 import { prepareSupervisorPrompt, superviseAgent } from "./supervise.mjs";
+import { prepareOrchestrationPrompt, orchestrateAgent } from "./orchestrate.mjs";
 import { supervisorId, registerSupervisor, getSupervisor, assertSupervisor, controlSupervisor, supervisorStatus, listSupervisors } from "./supervision.mjs";
 import { createFinding, findingStatus, listFindings, resolveFinding, dismissFinding, reopenFinding, evaluateFinding, findingStats } from "./findings.mjs";
 import { connectionMode, observationConnection, desktopReadOnly } from "./connection.mjs";
-import { listProjects } from "./projects.mjs";
+import { repairTurns } from "./turn-repair.mjs";
+import { listProjects, registeredRemoteProjects } from "./projects.mjs";
 import { createProjectThread } from "./thread-create.mjs";
+import { verifyProjectThread } from "./thread-verify.mjs";
+import { withDeviceAccount, prepareDevice, recoverDeviceKey, enrollDevice, pairDevice, verifyDevice, deviceStatus, deviceIdentityInfo, readPairingCode } from "./remote-device.mjs";
+import { readDevice } from "./remote-device-store.mjs";
+import { listRemoteProjects, listRemoteThreads, createRemoteProjectThread, verifyRemoteProjectThread, ensureRemoteDesktopSubscription } from "./remote-management.mjs";
 
 const DEFAULT_SEND_BACKEND = "app-server";
 
 function success(command, data, json) {
+  if (data && !Array.isArray(data)) Object.assign(data, hostFields());
   if (json) console.log(JSON.stringify({ ok: true, command, data }));
   return data;
 }
 
-function fail(error, json) {
+export function fail(error, json) {
   const message = error instanceof Error ? error.message : String(error);
   if (json) console.log(JSON.stringify({ ok: false, ...(error.watch ? { command: "watch", data: error.watch } : {}), error: {
-    message, code: error.code, delivery_status: error.delivery_status,
+    message, code: error.code, ...hostFields(), delivery_status: error.delivery_status,
     operation: error.operation, capability: error.capability,
+    ...((error.execution_environment === "cloud" || (typeof error.code === "string" && error.code.startsWith("CLOUD_"))) ? {
+      execution_environment: error.execution_environment, task_id: error.task_id, url: error.url,
+      submission_status: error.submission_status, uncertain: error.uncertain,
+      cli_exit_code: error.cli_exit_code, cli_signal: error.cli_signal,
+      http_status: error.http_status, retry_after_ms: error.retry_after_ms,
+    } : {}),
     sent: error.sent, thread_id: error.thread_id, rpc_code: error.rpc_code ?? error.rpcCode,
     message_id: error.message_id, client_message_id: error.client_message_id, journal_update_required: error.journal_update_required,
     existing_message_id: error.existing_message_id,
+    existing_attempt_id: error.existing_attempt_id, existing_receipt_path: error.existing_receipt_path,
     supervision_update_required: error.supervision_update_required,
-    receipt_path: error.receipt_path,
+    history_changed: error.history_changed, backup_path: error.backup_path, receipt_path: error.receipt_path,
+    repair_stat: error.repair_stat,
     creation_status: error.creation_status, attempt_id: error.attempt_id, receipt_update_required: error.receipt_update_required,
+    reservation_cleanup_required: error.reservation_cleanup_required,
     native_call_id: error.native_call_id,
+    uncertain: error.uncertain, resource: error.resource, lease_retained: error.lease_retained, remote_execution_status: error.remote_execution_status,
+    remote_process_id: error.remote_process_id,
+    verification_checks: error.verification_checks,
+    remote_control_auth: error.remote_control_auth,
   } }));
-  else console.error(`codexteer: ${message}`);
+  else {
+    console.error(`codexteer: ${message}`);
+    if (error.execution_environment === "cloud" || (typeof error.code === "string" && error.code.startsWith("DESKTOP_CLOUD_"))) {
+      // Recovery metadata must survive an uncertain submission or a stale
+      // on-disk receipt. Never print the child error, prompt, or diagnostics.
+      for (const key of ["creation_status", "submission_status", "delivery_status", "attempt_id", "receipt_path", "existing_attempt_id", "existing_receipt_path", "task_id", "thread_id", "url"]) {
+        if (typeof error[key] === "string") console.error(`${key}: ${JSON.stringify(error[key])}`);
+      }
+      if (error.receipt_update_required) console.error("receipt_update_required: true");
+      if (error.reservation_cleanup_required) console.error("reservation_cleanup_required: true");
+      if (Number.isSafeInteger(error.retry_after_ms)) console.error(`retry_after_ms: ${error.retry_after_ms}`);
+    }
+  }
   process.exitCode = 1;
 }
 
@@ -64,6 +98,23 @@ function takeOptions(args, name) {
   return values;
 }
 
+function routingThread(probe) {
+  const valued = new Set(["--backend", "--source", "--kind", "--evidence", "--based-on", "--supersedes", "--expires-at", "--checkpoint", "--finding",
+    "--wait-ms", "--limit", "--max-chars", "--since", "--until", "--timeout-ms", "--poll-ms", "--notify", "--settle-ms", "--max-hold-ms",
+    "--owner", "--agent", "--status", "--note", "--by", "--reason", "--condition", "--ttl-ms", "--token", "--cwd", "--exec-backend", "--shell", "--key", "--title", "--rating", "--path", "--exclude", "--artifact"]);
+  const positional = [];
+  for (let i = 0; i < probe.length; i++) {
+    if (probe[i] === "--") { positional.push(...probe.slice(i + 1)); break; }
+    if (probe[i].startsWith("--")) { if (valued.has(probe[i])) i++; continue; }
+    positional.push(probe[i]);
+  }
+  const [command, action] = positional;
+  if (/^(codex:\/\/|[0-9a-f]{8}-)/i.test(command ?? "")) return command;
+  const nested = ["history", "instructions", "findings", "checkpoint", "thread"].includes(command)
+    || (command === "supervise" && ["prompt", "register", "status", "pause", "resume", "stop", "list"].includes(action));
+  return positional[nested ? 2 : 1];
+}
+
 function readMessage(parts) {
   if (parts[0] === "--") parts.shift();
   if (parts.length === 1 && parts[0] === "-") return readFileSync(0, "utf8");
@@ -106,6 +157,35 @@ function printSupervisor(data) {
 }
 
 export async function main(argv) {
+  const args = [...argv];
+  try {
+    const transport = validateRemoteTransport(takeOption(args, "--remote-transport", "native"));
+    const explicitHost = takeOption(args, "--host", undefined);
+    if (args.slice(0, args.includes("--") ? args.indexOf("--") : args.length).includes("--host")) throw new Error("Specify --host only once.");
+    if (explicitHost !== undefined) validateHostId(explicitHost);
+    const probe = [...args];
+    takeFlag(probe, "--json");
+    for (const flag of ["--connection", "--supervisor", "--require-node-version"]) takeOption(probe, flag, undefined);
+    takeOption(probe, "--context-thread", undefined);
+    const command = probe[0];
+    const contextThread = takeOption(args, "--context-thread", undefined);
+    let candidate;
+    if (command === "doctor") candidate = takeOption(probe, "--thread", undefined);
+    else if (command === "resource") candidate = takeOption(probe, "--thread", undefined);
+    else if (["read", "status", "watch", "send", "open", "debug-ui", "supervise", "history", "instructions", "findings", "checkpoint"].includes(command)
+      || (command === "thread" && ["resolve", "repair"].includes(probe[1])) || /^(codex:\/\/|[0-9a-f]{8}-)/i.test(command ?? "")) {
+      candidate = routingThread(probe);
+    }
+    const linkHost = candidate === undefined ? undefined : parseThreadTarget(candidate).hostId;
+    if (explicitHost !== undefined && linkHost !== undefined && explicitHost !== linkHost) throw Object.assign(new Error("--host conflicts with the thread link hostId."), { code: "HOST_MISMATCH" });
+    const host = linkHost ?? explicitHost ?? "local";
+    const ownArguments = probe.slice(0, probe.includes("--") ? probe.indexOf("--") : probe.length);
+    if (isControlTransport(transport) && host === "local" && command !== "remote" && !["help", "--help", "--version"].some(value => ownArguments.includes(value))) throw Object.assign(new Error("--remote-transport control requires a remote hostId link or --host."), { code: "REMOTE_HOST_REQUIRED" });
+    return await withTarget(host, contextThread, () => mainOnTarget(args), { transport });
+  } catch (error) { fail(error, argv.includes("--json")); }
+}
+
+async function mainOnTarget(argv) {
   const args = [...argv];
   let json = takeFlag(args, "--json");
 
@@ -127,7 +207,7 @@ export async function main(argv) {
     if (args.length === 0 || takeFlag(args, "--help") || args[0] === "help") {
       if (args[0] === "help") args.shift();
       const candidate = args[0] ?? "overview";
-      const topic = candidate === "supervise" && args[1] === "prompt" ? "supervise prompt"
+      const topic = ["supervise", "orchestrate"].includes(candidate) && args[1] === "prompt" ? `${candidate} prompt`
         : /^(codex:\/\/|[0-9a-f]{8}-)/i.test(candidate) ? "send" : candidate;
       const data = helpData(topic);
       success("help", data, json);
@@ -136,9 +216,32 @@ export async function main(argv) {
     }
 
     let command = args.shift();
+    const control = isControlTransport();
+    if (targetHost() !== "local" && ["desktop", "debug-ui"].includes(command)) throw Object.assign(new Error("Desktop process/update and Accessibility diagnostics cannot target the remote host. No local operation was run."), { code: "REMOTE_HOST_OPERATION_UNSUPPORTED" });
+    if (targetHost() !== "local" && !["remote", "projects", "read", "status", "watch", "doctor", "supervise", "findings", "history", "instructions", "thread", "open", ...(control ? ["send"] : []), ...(remoteTransport() === "paired" ? ["threads", "resource", "checkpoint", "orchestrate"] : [])].includes(command)
+      && !(control && /^(codex:\/\/|[0-9a-f]{8}-)/i.test(command))) throw remoteReadOnly();
+    if (targetHost() !== "local" && command === "thread" && args[0] !== "resolve" && remoteTransport() !== "paired") throw remoteReadOnly();
+    if (targetHost() !== "local" && command === "thread" && args[0] === "repair") throw Object.assign(new Error("Offline rollout repair is supported only for validated local macOS/CLI versions. The remote history was not modified."), { code: "REMOTE_REPAIR_UNSUPPORTED" });
+    if (targetHost() !== "local" && command === "instructions" && args[0] !== "list" && !control) throw remoteReadOnly();
     // An explicit observation endpoint can never silently route a mutation to
     // the shared wrapper or UI. Local records/help remain available.
     if (connection === "desktop" && !["supervise", "findings", "history", "instructions", "checkpoint", "resource", "read", "status", "watch", "doctor", "threads", "thread"].includes(command)) throw desktopReadOnly();
+    if (command === "remote") {
+      if (supervisor) throw Object.assign(new Error("A bound supervisor cannot enroll, pair or manage account credentials."), { code: "SUPERVISOR_MISMATCH" });
+      const action = args.shift(), codeStdin = takeFlag(args, "--code-stdin"), provider = takeOption(args, "--key-provider", undefined);
+      if (provider !== undefined && action !== "prepare") throw new Error("--key-provider is only available for remote prepare.");
+      if (!["prepare", "recover-key", "enroll", "status", "identity", "pair", "verify"].includes(action) || args.length || (codeStdin && action !== "pair") || (action === "pair" && !codeStdin)) throw new Error("Expected: remote prepare|recover-key|enroll|status|identity|verify, or --host HOST remote pair --code-stdin.");
+      if (["prepare", "enroll"].includes(action) && targetHost() !== "local") throw new Error("remote prepare/enroll registers this local controller; omit --host.");
+      // Code input is never an argv option or a chat message.
+      if (action === "pair" && !/^remote-control:env_[A-Za-z0-9_-]+$/.test(targetHost())) throw new Error("remote pair requires --host remote-control:env_...");
+      if (action === "pair" && process.stdin.isTTY) console.error("codexteer: Enter the selected host's fresh pairing code (hidden), then press Enter.");
+      const code = action === "pair" ? await readPairingCode() : undefined;
+      if (code && code.length > 128) throw new Error("Invalid pairing code input.");
+      const data = await withDeviceAccount(context => action === "prepare" ? prepareDevice(context, { ...(provider ? { provider } : {}) }) : action === "recover-key" ? recoverDeviceKey(context) : action === "enroll" ? enrollDevice(context, { progress: text => console.error(`codexteer: ${text}`) })
+        : action === "pair" ? pairDevice(context, targetHost(), code)
+          : action === "verify" ? verifyDevice(context) : action === "identity" ? deviceIdentityInfo(context) : readDevice(context.home, context.identity).then(deviceStatus));
+      success(`remote.${action}`, data, json); if (!json) console.log(JSON.stringify(data, null, 2)); return;
+    }
     if (command === "supervise" && ["register", "status", "list", "pause", "resume", "stop"].includes(args[0])) {
       const action = args.shift(), owner = action === "register" ? takeOption(args, "--owner", "external") : undefined;
       if (args.length !== (action === "list" ? 0 : 1)) throw new Error(`Expected: supervise ${action}${action === "list" ? "" : " <THREAD>"}.`);
@@ -184,6 +287,28 @@ export async function main(argv) {
       if (!json) console.log(JSON.stringify(data, null, 2));
       return;
     }
+    if (command === "orchestrate") {
+      if (supervisor) throw Object.assign(new Error("Managed supervision is bound to its existing task and cannot orchestrate a project."), { code: "SUPERVISOR_CONTROL_FORBIDDEN" });
+      const promptOnly = args[0] === "prompt";
+      if (promptOnly) args.shift();
+      else if (json) throw new Error("orchestrate inherits agent output and does not support --json. Use help orchestrate --json or orchestrate prompt --project ID|NAME <GOAL> --json.");
+      const separator = promptOnly ? -1 : args.indexOf("--");
+      const ownArgs = separator < 0 ? args : args.slice(0, separator);
+      const agentArgs = separator < 0 ? [] : args.slice(separator + 1);
+      const project = takeOption(ownArgs, "--project", undefined);
+      const agent = takeOption(ownArgs, "--agent", promptOnly ? undefined : "claude");
+      const usePathCli = takeFlag(ownArgs, "--use-path-cli");
+      if (promptOnly && ownArgs[0] === "--") ownArgs.shift();
+      else if (ownArgs.some(arg => arg.startsWith("--"))) throw new Error("Unknown orchestrate option. See help orchestrate; agent arguments belong after --.");
+      if (ownArgs.length !== 1) throw new Error("Expected: orchestrate [prompt] --project <ID-or-exact-name> <GOAL>. Quote the goal as one argument, or use - for stdin.");
+      const goal = ownArgs[0] === "-" ? readFileSync(0, "utf8") : ownArgs[0];
+      if (promptOnly) {
+        const data = await prepareOrchestrationPrompt(project, goal, { agent, connection, usePathCli });
+        success("orchestrate.prompt", data, json);
+        if (!json) console.log(data.prompt);
+      } else process.exitCode = await orchestrateAgent(project, goal, { agent, agentArgs, connection, usePathCli });
+      return;
+    }
     if (command === "supervise" && args[0] === "prompt") {
       args.shift();
       const agent = takeOption(args, "--agent", "claude");
@@ -210,11 +335,12 @@ export async function main(argv) {
     if (command === "resource") {
       const action = args.shift(); let data;
       if (["acquire", "run"].includes(action)) {
-        const options = { owner: takeOption(args, "--owner", undefined), ttlMs: Number(takeOption(args, "--ttl-ms", "600000")), reason: takeOption(args, "--reason", ""), condition: takeOption(args, "--condition", ""), threadId: takeOption(args, "--thread", undefined) };
+        const options = { owner: takeOption(args, "--owner", undefined), ttlMs: Number(takeOption(args, "--ttl-ms", "600000")), reason: takeOption(args, "--reason", ""), condition: takeOption(args, "--condition", ""), threadId: takeOption(args, "--thread", undefined), cwd: takeOption(args, "--cwd", undefined) };
         if (action === "run") {
-          const timeoutMs = Number(takeOption(args, "--timeout-ms", "0")), includeOutput = takeFlag(args, "--include-output");
+          const timeoutMs = Number(takeOption(args, "--timeout-ms", "0")), includeOutput = takeFlag(args, "--include-output"), execBackend = takeOption(args, "--exec-backend", "app-server"), remoteShell = takeOption(args, "--shell", undefined);
+          if (supervisor) await assertSupervisor(options.threadId, supervisor, { connection, sending: execBackend === "thread-shell" });
           if (args[1] !== "--" || args.length < 3) throw new Error("Expected: resource run <NAME> --owner NAME -- <COMMAND> [ARGS...]");
-          data = await runWithResource(args[0], args.slice(2), { ...options, timeoutMs });
+          data = await runWithResource(args[0], args.slice(2), { ...options, timeoutMs, execBackend, remoteShell, supervisor, connection });
           if (!includeOutput) delete data.output_tail;
           if (!data.valid) process.exitCode = 1;
         } else {
@@ -241,9 +367,10 @@ export async function main(argv) {
         if (args.length !== 2) throw new Error("Expected: checkpoint capture <THREAD> <NAME> --path PATH ...");
         data = await createCheckpoint(args[0], args[1], { paths, excludes });
       } else if (action === "run") {
-        const timeoutMs = Number(takeOption(args, "--timeout-ms", "0"));
+        const timeoutMs = Number(takeOption(args, "--timeout-ms", "0")), execBackend = takeOption(args, "--exec-backend", "app-server"), remoteShell = takeOption(args, "--shell", undefined);
+        if (supervisor && execBackend === "thread-shell") await assertSupervisor(args[0], supervisor, { connection, sending: true });
         if (args[2] !== "--" || args.length < 4) throw new Error("Expected: checkpoint run <THREAD> <ID> -- <COMMAND> [ARGS...]");
-        data = await runCheckpoint(args[0], args[1], args.slice(3), { timeoutMs });
+        data = await runCheckpoint(args[0], args[1], args.slice(3), { timeoutMs, execBackend, remoteShell, supervisor, connection });
         if (!includeOutput) delete data.output_tail;
         if (!data.valid) process.exitCode = 1;
       } else if (action === "attach") {
@@ -338,8 +465,9 @@ export async function main(argv) {
         if (record?.session_id === supervisor) await assertSupervisor(threadId, supervisor, { connection });
       }
       if (args.length) throw new Error(`Unexpected argument: ${args[0]}`);
+      if (targetHost() !== "local" && backend === "ui") throw remoteReadOnly();
       const report = backend === "ui" ? desktopDoctor() : await appServerDoctor({ threadId, ...connectionDependencies });
-      if (report.connection) Object.assign(report.connection, { mode: connection, observation_only: connection === "desktop" });
+      if (report.connection) Object.assign(report.connection, { mode: connection, observation_only: connection === "desktop" || (targetHost() !== "local" && !control), ...hostFields() });
       report.default_send_backend = DEFAULT_SEND_BACKEND;
       report.rollout_status = "enabled";
       success("doctor", report, json);
@@ -366,7 +494,25 @@ export async function main(argv) {
     }
 
     if (command === "desktop") {
-      if (args.shift() !== "start") throw new Error("Expected: codexteer desktop start");
+      const action = args.shift();
+      if (action === "update-status") {
+        if (args.length) throw new Error(`Unexpected argument: ${args[0]}`);
+        const data = await desktopUpdateStatus();
+        success("desktop.update-status", data, json);
+        if (!json) console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      if (action === "update") {
+        if (supervisor) throw Object.assign(new Error("A supervisor cannot update or restart Desktop. Run this command from the user's terminal without --supervisor."), { code: "SUPERVISOR_CONTROL_FORBIDDEN" });
+        const dryRun = takeFlag(args, "--dry-run");
+        const timeoutMs = Number(takeOption(args, "--timeout-ms", "600000"));
+        if (args.length) throw new Error(`Unexpected argument: ${args[0]}`);
+        const data = await launchDesktopUpdate({ dryRun, timeoutMs });
+        success("desktop.update", data, json);
+        if (!json) console.log(dryRun ? "Dry run: official update, relaunch, normal quit, wrapper startup, and verification." : `Update worker started (${data.worker_pid}). Check: ${data.status_command}`);
+        return;
+      }
+      if (action !== "start") throw new Error("Expected: codexteer desktop start|update|update-status");
       const dryRun = takeFlag(args, "--dry-run");
       if (args.length) throw new Error(`Unexpected argument: ${args[0]}`);
       const data = await startDesktop({ dryRun });
@@ -377,10 +523,15 @@ export async function main(argv) {
 
     if (command === "projects") {
       if (connection === "desktop") throw desktopReadOnly();
-      if (args.shift() !== "list" || args.length) throw new Error("Expected: codexteer projects list");
-      const projects = await listProjects();
+      if (args.shift() !== "list") throw new Error("Expected: codexteer projects list [--remote | --all] [--host HOST-ID]");
+      const remote = takeFlag(args, "--remote"), all = takeFlag(args, "--all");
+      if (args.length || (remote && all) || (all && targetHost() !== "local")) throw new Error("Use projects list [--remote | --all] or projects list --host HOST-ID.");
+      const saved = targetHost() !== "local" && remoteTransport() === "paired" ? await listRemoteProjects()
+        : remote || all || targetHost() !== "local" ? await registeredRemoteProjects() : [];
+      const projects = [...(!remote && (all || targetHost() === "local") ? await listProjects() : []),
+        ...saved.filter(project => targetHost() === "local" || project.host_id === targetHost())];
       success("projects.list", { projects, count: projects.length }, json);
-      if (!json) for (const project of projects) console.log(`${project.project_id}  ${project.name}\n${project.roots.map(root => `  ${root}`).join("\n")}`);
+      if (!json) for (const project of projects) console.log(`${project.project_id}  ${project.name}${project.host_id ? `  [${project.host_id}; availability: ${project.availability}]` : ""}\n${project.roots.map(root => `  ${root}`).join("\n")}`);
       return;
     }
 
@@ -388,18 +539,31 @@ export async function main(argv) {
       if (args.shift() !== "list") throw new Error("Expected: codexteer threads list");
       const limit = Number.parseInt(takeOption(args, "--limit", "20"), 10);
       const desktopOnly = takeFlag(args, "--desktop-only");
+      const cursor = takeOption(args, "--cursor", undefined), projectId = takeOption(args, "--project", undefined), search = takeOption(args, "--search", undefined);
       if (args.length > 0) throw new Error(`Unexpected argument: ${args[0]}`);
       if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
         throw new Error("--limit must be an integer between 1 and 500.");
       }
-      const threads = await listLocalThreads({ limit, desktopOnly });
-      success("threads.list", { threads, count: threads.length }, json);
+      if (targetHost() === "local" && [cursor, projectId, search].some(value => value !== undefined)) throw new Error("--cursor/--project/--search currently require a paired remote host.");
+      const data = targetHost() === "local" ? { threads: await listLocalThreads({ limit, desktopOnly }) } : await listRemoteThreads({ limit, desktopOnly, cursor, projectId, search });
+      const threads = data.threads;
+      success("threads.list", { ...data, count: threads.length }, json);
       if (!json) printThreads(threads);
       return;
     }
 
     if (command === "thread") {
       const action = args.shift();
+      if (action === "verify") {
+        if (connection === "desktop") throw desktopReadOnly();
+        if (supervisor) throw Object.assign(new Error("Managed supervision is bound to its existing task. Verify a project creation receipt without --supervisor."), { code: "SUPERVISOR_CONTROL_FORBIDDEN" });
+        const timeoutMs = Number(takeOption(args, "--timeout-ms", "120000"));
+        if (args.length !== 1 || args[0].startsWith("--")) throw new Error("Expected: thread verify <ATTEMPT-ID> [--timeout-ms N].");
+        const data = await (targetHost() === "local" ? verifyProjectThread : verifyRemoteProjectThread)(args[0], { timeoutMs });
+        success("thread.verify", data, json);
+        if (!json) console.log(`Verified existing ${data.deep_link}; creation and initial instruction were not repeated.`);
+        return;
+      }
       if (action === "create") {
         if (connection === "desktop") throw desktopReadOnly();
         if (supervisor) throw Object.assign(new Error("Managed supervision is bound to its existing task. Run thread create without --supervisor under the user's delegated creation scope."), { code: "SUPERVISOR_CONTROL_FORBIDDEN" });
@@ -407,19 +571,29 @@ export async function main(argv) {
         const options = { title: takeOption(args, "--title", undefined), cwd: takeOption(args, "--cwd", undefined), model: takeOption(args, "--model", undefined),
           permissions: takeOption(args, "--permissions", undefined), sandbox: takeOption(args, "--sandbox", undefined),
           approvalPolicy: takeOption(args, "--approval-policy", undefined), approvalsReviewer: takeOption(args, "--approvals-reviewer", undefined), dryRun: takeFlag(args, "--dry-run"),
-          contextThread: takeOption(args, "--context-thread", undefined), thinking: takeOption(args, "--thinking", undefined), timeoutMs: takeOption(args, "--timeout-ms", undefined) };
+          contextThread: targetContext(), thinking: takeOption(args, "--thinking", undefined), timeoutMs: takeOption(args, "--timeout-ms", undefined) };
         if (options.timeoutMs !== undefined) {
           options.timeoutMs = Number(options.timeoutMs);
         }
         const literal = args.indexOf("--");
         if (args.slice(0, literal < 0 ? args.length : literal).some(arg => arg.startsWith("--"))) throw new Error("Unknown thread create option. Use -- before an instruction starting with --.");
         const message = readMessage(args);
-        const data = await createProjectThread(selector, message, options);
+        const data = await (targetHost() === "local" ? createProjectThread : createRemoteProjectThread)(selector, message, options);
         success("thread.create", data, json);
         if (!json) console.log(options.dryRun ? `Dry run: ${data.project_name} (${data.cwd}), ${data.message_characters} characters.` : `Created ${data.deep_link} in ${data.project_name}; initial instruction accepted${data.turn_id ? ` (turn ${data.turn_id})` : ""}.`);
         return;
       }
-      if (action !== "resolve") throw new Error("Expected: codexteer thread create|resolve. See help thread.");
+      if (action === "repair") {
+        const apply = takeFlag(args, "--apply"), dryRun = takeFlag(args, "--dry-run");
+        if (args.length !== 1 || args[0].startsWith("--") || (apply && dryRun)) throw new Error("Expected: thread repair <THREAD> [--dry-run | --apply].");
+        if (connection === "desktop") throw desktopReadOnly();
+        if (supervisor) throw Object.assign(new Error("A supervisor cannot repair task history. Run this command from the user's terminal without --supervisor."), { code: "SUPERVISOR_CONTROL_FORBIDDEN" });
+        const data = await repairTurns(args[0], { apply });
+        success("thread.repair", data, json);
+        if (!json) console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      if (action !== "resolve") throw new Error("Expected: codexteer thread create|verify|resolve|repair. See help thread.");
       if (args.length !== 1) throw new Error("thread resolve requires exactly one thread ID or URL.");
       const threadId = normalizeThreadId(args[0]);
       const data = { thread_id: threadId, deep_link: threadDeepLink(threadId) };
@@ -431,7 +605,7 @@ export async function main(argv) {
     if (command === "open") {
       if (args.length !== 1) throw new Error("open requires exactly one thread ID or URL.");
       const threadId = normalizeThreadId(args[0]);
-      const data = openDesktopThread(threadId);
+      const data = targetHost() === "local" ? openDesktopThread(threadId) : await ensureRemoteDesktopSubscription(threadId);
       success("open", data, json);
       if (!json) console.log(`Opened ${data.deep_link}`);
       return;
@@ -454,6 +628,10 @@ export async function main(argv) {
 
     const dryRun = takeFlag(args, "--dry-run");
     const backend = backendOption(args, DEFAULT_SEND_BACKEND);
+    if (targetHost() !== "local" && backend === "ui") {
+      if (remoteTransport() !== "paired") throw remoteReadOnly();
+      throw Object.assign(new Error("UI sending on the remote host is unsupported. No UI or other delivery route was used."), { code: "REMOTE_UI_UNSUPPORTED", sent: false, delivery_status: "not_sent" });
+    }
     if (supervisor && backend !== "app-server") throw new Error("Managed supervision requires the app-server backend.");
     const explicitSound = takeFlag(args, "--sound");
     const noSound = takeFlag(args, "--no-sound");

package/src/cloud-api.mjs

@@ -0,0 +1,118 @@
+import { spawn } from "node:child_process";
+import { VERSION } from "./version.mjs";
+
+const failure = (code, message) => Object.assign(new Error(message), { code, execution_environment: "cloud" });
+const LIMIT = 16 * 1024 * 1024;
+
+// Credentials stay in memory and come from the official process, never auth.json.
+// No model session is started and no Desktop connection is used.
+export function cloudCredentials({ spawnProcess = spawn, timeoutMs = 15000, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(failure("CLOUD_CANCELLED", "Cloud authentication was cancelled.")); return; }
+    let child, buffer = "", bytes = 0, settled = false, killTimer, initialized = false;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer); signal?.removeEventListener("abort", cancel);
+      child?.stdin.destroy(); child?.kill();
+      killTimer = setTimeout(() => child?.kill("SIGKILL"), 500); killTimer.unref();
+      buffer = "";
+      if (error) reject(error); else resolve(result);
+    };
+    const cancel = () => finish(failure("CLOUD_CANCELLED", "Cloud authentication was cancelled."));
+    const timer = setTimeout(() => finish(failure("CLOUD_AUTH_TIMEOUT", "Official CLI authentication timed out.")), timeoutMs);
+    signal?.addEventListener("abort", cancel, { once: true });
+    try { child = spawnProcess("codex", ["app-server", "--listen", "stdio://"], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true }); }
+    catch { finish(failure("CLOUD_AUTH_UNAVAILABLE", "Cannot start the official Codex App Server.")); return; }
+    child.on("error", () => finish(failure("CLOUD_AUTH_UNAVAILABLE", "Cannot start the official Codex App Server.")));
+    child.on("close", () => { clearTimeout(killTimer); finish(failure("CLOUD_AUTH_FAILED", "Official CLI authentication closed before completion.")); });
+    const count = chunk => { bytes += Buffer.byteLength(chunk); if (bytes > LIMIT) finish(failure("CLOUD_OUTPUT_LIMIT", "Official authentication exceeded the response limit.")); };
+    child.stderr.on("data", count);
+    child.stdin.on("error", () => finish(failure("CLOUD_AUTH_FAILED", "Official CLI authentication failed.")));
+    const send = value => child.stdin.write(JSON.stringify(value) + "\n");
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", chunk => {
+      count(chunk); if (settled) return;
+      buffer += chunk;
+      let newline;
+      while (!settled && (newline = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+        let message;
+        try { message = JSON.parse(line); } catch { finish(failure("CLOUD_AUTH_PROTOCOL", "Invalid official authentication response.")); return; }
+        if (message.id === 1) {
+          if (initialized || !message.result || message.error) { finish(failure("CLOUD_AUTH_PROTOCOL", "Official authentication initialization failed.")); return; }
+          initialized = true;
+          send({ method: "initialized" });
+          send({ id: 2, method: "getAuthStatus", params: { includeToken: true, refreshToken: false } });
+        } else if (message.id === 2) {
+          const result = message.result;
+          if (!initialized || message.error || result?.authMethod !== "chatgpt" || typeof result.authToken !== "string" || !result.authToken || /[\s\x00-\x1f\x7f]/u.test(result.authToken)) {
+            finish(failure("CLOUD_LOGIN_REQUIRED", "Sign in to the official Codex CLI with ChatGPT to list cloud environments.")); return;
+          }
+          let accountId;
+          try { accountId = JSON.parse(Buffer.from(result.authToken.split(".")[1], "base64url").toString("utf8"))["https://api.openai.com/auth"]?.chatgpt_account_id; } catch {}
+          if (typeof accountId !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(accountId)) { finish(failure("CLOUD_AUTH_PROTOCOL", "Official authentication did not identify a ChatGPT account.")); return; }
+          finish(null, { token: result.authToken, accountId });
+        }
+      }
+    });
+    send({ id: 1, method: "initialize", params: { clientInfo: { name: "codexteer", version: VERSION } } });
+  });
+}
+
+// Fixed official origin, no redirects, URL overrides, raw diagnostics or retries.
+export async function cloudApi(route, { timeoutMs = 120000, credentials = cloudCredentials, fetchRequest = fetch, body, signal } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600000) throw failure("CLOUD_OPTIONS_INVALID", "Invalid cloud request deadline.");
+  if (!(body === undefined ? /^(?:environments|tasks\/task_[A-Za-z0-9_-]{1,200}(?:\/turns)?)$/.test(route) : route === "tasks")) throw failure("CLOUD_OPTIONS_INVALID", "Unsupported cloud API route.");
+  if (signal?.aborted) throw failure("CLOUD_CANCELLED", "Cloud request was cancelled.");
+  const started = Date.now();
+  let auth;
+  try { auth = await credentials({ timeoutMs: Math.min(timeoutMs, 15000), signal }); }
+  catch (error) {
+    if (error.code === "CLOUD_AUTH_TIMEOUT" && Date.now() - started >= timeoutMs) throw failure("CLOUD_TIMEOUT", "Cloud authentication exceeded the request deadline.");
+    throw error;
+  }
+  const remaining = timeoutMs - (Date.now() - started);
+  if (remaining <= 0) throw failure("CLOUD_TIMEOUT", "Cloud authentication exceeded the request deadline.");
+  const controller = new AbortController(), timer = setTimeout(() => controller.abort(), remaining);
+  const cancel = () => controller.abort(); signal?.addEventListener("abort", cancel, { once: true });
+  if (signal?.aborted) controller.abort();
+  try {
+    const response = await fetchRequest(`https://chatgpt.com/backend-api/wham/${route}`, {
+      method: body === undefined ? "GET" : "POST", redirect: "error", signal: controller.signal,
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      headers: { Authorization: `Bearer ${auth.token}`, "ChatGPT-Account-ID": auth.accountId, Accept: "application/json", "Content-Type": "application/json", "User-Agent": `codexteer/${VERSION}` },
+    });
+    if (!response.ok) {
+      await response.body?.cancel();
+      if (response.status === 429) {
+        const header = response.headers.get("retry-after"), seconds = header != null && /^\d+(?:\.\d+)?$/.test(header) ? Number(header) : null;
+        const after = seconds !== null ? Math.min(Number.MAX_SAFE_INTEGER, seconds * 1000) : header == null ? NaN : Date.parse(header) - Date.now();
+        throw Object.assign(failure("CLOUD_RATE_LIMITED", "Cloud requests are rate limited. Respect retry_after_ms before another read; no request was retried."), {
+          http_status: 429, retry_after_ms: Number.isFinite(after) ? Math.max(1000, Math.min(Number.MAX_SAFE_INTEGER, Math.ceil(after))) : 15000,
+        });
+      }
+      throw failure(response.status === 401 ? "CLOUD_LOGIN_REQUIRED" : response.status === 403 ? "CLOUD_ACCESS_DENIED" : "CLOUD_HTTP_FAILED", `Cloud request failed (HTTP ${response.status}). No response body or credentials were disclosed.`);
+    }
+    let bytes = 0; const chunks = [];
+    for await (const chunk of response.body) {
+      bytes += chunk.length; if (bytes > LIMIT) { controller.abort(); throw failure("CLOUD_OUTPUT_LIMIT", "Cloud response exceeded the 16 MiB limit."); }
+      chunks.push(chunk);
+    }
+    try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+    catch { throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud returned an unrecognized response. No raw payload was disclosed."); }
+  } catch (error) {
+    if (typeof error.code === "string" && error.code.startsWith("CLOUD_")) throw error;
+    throw failure(signal?.aborted ? "CLOUD_CANCELLED" : controller.signal.aborted ? "CLOUD_TIMEOUT" : "CLOUD_CONNECTION_FAILED", "Cloud request did not complete. No credentials or raw diagnostics were disclosed.");
+  } finally { clearTimeout(timer); signal?.removeEventListener("abort", cancel); }
+}
+
+export async function cloudEnvironments(settings = {}, { request = cloudApi } = {}) {
+  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 rows = await request("environments", settings);
+  if (!Array.isArray(rows) || rows.length > 10000 || rows.some(row => !row || typeof row.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/.test(row.id)
+    || (row.label != null && (typeof row.label !== "string" || row.label.length > 1000)))) throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud returned an unrecognized environment inventory.");
+  return { backend: "codex-api", execution_environment: "cloud", environments: rows.map(row => ({ id: row.id, name: row.label ?? null, pinned: row.is_pinned === true,
+    repositories: Object.values(row.repo_map ?? {}).flatMap(repo => typeof repo?.repository_full_name === "string" && repo.repository_full_name.length < 1000
+      ? [{ name: repo.repository_full_name, default_branch: typeof repo.default_branch === "string" && repo.default_branch.length < 256 ? repo.default_branch : null }] : []),
+  })), source: "accessible-task-environments", availability: "listed-access-only; execution-not-verified" };
+}