codexteer 0.16.0 → 0.18.0

package/src/checkpoint.mjs

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

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,28 +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 { 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,
+    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;
 }
 
@@ -59,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");
@@ -101,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");
 
@@ -122,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);
@@ -131,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>"}.`);
@@ -179,12 +287,35 @@ 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");
+      const usePathCli = takeFlag(args, "--use-path-cli");
       if (args.length < 1 || args.length > 2 || args.some(arg => arg.startsWith("--"))) throw new Error("Expected: supervise prompt <THREAD> [MESSAGE]. See codexteer help supervise prompt.");
       if (supervisor) throw new Error("A supervisor cannot generate a replacement session.");
-      const data = await prepareSupervisorPrompt(args[0], args[1], { agent, connection });
+      const data = await prepareSupervisorPrompt(args[0], args[1], { agent, connection, usePathCli });
       success("supervise.prompt", data, json);
       if (!json) console.log(data.prompt);
       return;
@@ -196,18 +327,20 @@ export async function main(argv) {
       const ownArgs = separator < 0 ? args : args.slice(0, separator);
       const agentArgs = separator < 0 ? [] : args.slice(separator + 1);
       const agent = takeOption(ownArgs, "--agent", "claude");
-      if (ownArgs.length < 1 || ownArgs.length > 2 || ownArgs.some(arg => arg.startsWith("--"))) throw new Error("Expected: supervise <THREAD> [MESSAGE] [--agent claude|codex] [-- <AGENT-ARGS...>].");
-      process.exitCode = await superviseAgent(ownArgs[0], { agent, agentArgs, policy: ownArgs[1], connection });
+      const usePathCli = takeFlag(ownArgs, "--use-path-cli");
+      if (ownArgs.length < 1 || ownArgs.length > 2 || ownArgs.some(arg => arg.startsWith("--"))) throw new Error("Expected: supervise <THREAD> [MESSAGE] [--agent claude|codex] [--use-path-cli] [-- <AGENT-ARGS...>].");
+      process.exitCode = await superviseAgent(ownArgs[0], { agent, agentArgs, policy: ownArgs[1], connection, usePathCli });
       return;
     }
     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 {
@@ -234,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") {
@@ -331,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);
@@ -359,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 });
@@ -368,22 +521,79 @@ export async function main(argv) {
       return;
     }
 
+    if (command === "projects") {
+      if (connection === "desktop") throw desktopReadOnly();
+      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}${project.host_id ? `  [${project.host_id}; availability: ${project.availability}]` : ""}\n${project.roots.map(root => `  ${root}`).join("\n")}`);
+      return;
+    }
+
     if (command === "threads") {
       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") {
-      if (args.shift() !== "resolve") throw new Error("Expected: codexteer thread resolve <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" });
+        const selector = takeOption(args, "--project", undefined);
+        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: 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 (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 === "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) };
@@ -395,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;
@@ -418,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");