codexteer 0.16.0 → 0.18.0

package/src/desktop-cloud-id.mjs

@@ -0,0 +1,18 @@
+import { normalizeThreadId } from "./thread-id.mjs";
+export function isDesktopCloudTask(value) {
+  if (typeof value !== "string") return false;
+  if (value.startsWith("durable_")) return true;
+  try { const u = new URL(value); return u.protocol === "codex:" && u.hostname === "threads" && u.searchParams.getAll("hostId").includes("durable"); } catch { return false; }
+}
+export function desktopCloudId(value) {
+  if (!isDesktopCloudTask(value)) throw Object.assign(new Error("Desktop Cloud requires a durable_ ID or a link with hostId=durable."), { code: "CLOUD_TARGET_CONFLICT" });
+  let uuid = value.slice(8);
+  if (!value.startsWith("durable_")) {
+    const url = new URL(value);
+    if (url.searchParams.getAll("hostId").length !== 1 || url.username || url.password || url.port) throw Object.assign(new Error("Ambiguous Desktop Cloud link."), { code: "CLOUD_TARGET_CONFLICT" });
+    uuid = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
+  }
+  return "durable_" + normalizeThreadId(uuid);
+}
+export const desktopCloudUuid = value => desktopCloudId(value).slice(8);
+export const desktopCloudLink = value => `codex://threads/${desktopCloudUuid(value)}?hostId=durable`;

package/src/desktop-cloud-project.mjs

@@ -0,0 +1,148 @@
+import { createHash, createPublicKey, randomBytes, randomUUID, verify } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { discoverRuntime, codexHome } from "./runtime.mjs";
+import { BUNDLED_NODE } from "./wrapper.mjs";
+import { discoverNativeEndpoint, nativeRpc, inspectNativeEndpoint } from "./native-rpc.mjs";
+import { connectDesktopCloud } from "./desktop-cloud-api.mjs";
+import { desktopCloudId, desktopCloudUuid } from "./desktop-cloud-id.mjs";
+import { listProjects } from "./projects.mjs";
+import { listRecords, readRecord, writeRecord, withStoreLock, storePath } from "./store.mjs";
+const failure = (message, code = "DESKTOP_CLOUD_PROJECT_UNAVAILABLE", uncertain = false) => Object.assign(new Error(message), { code, uncertain });
+const sha = value => createHash("sha256").update(value).digest("hex");
+
+export async function discoverProjectApi({ discover = discoverRuntime, endpoint = discoverNativeEndpoint, run = spawnSync } = {}) {
+  const selected = await discover(), { state } = selected;
+  const owned = run("/bin/ps", ["-p", String(state.pid), "-o", "uid=", "-o", "comm="], { encoding: "utf8", timeout: 3000 });
+  const owner = owned.stdout?.trim().match(/^(\d+)\s+(.+)$/);
+  if (owned.status !== 0 || !owner || Number(owner[1]) !== process.getuid() || owner[2] !== BUNDLED_NODE || state.node_path !== BUNDLED_NODE) throw failure("Cannot verify the selected Desktop process.");
+  const target = await endpoint(state);
+  // Extract only the inherited endpoint and public verification key from this
+  // one owner-validated process. Never emit or persist its environment.
+  const processEnv = run("/bin/ps", ["eww", "-p", String(state.pid), "-o", "command="], { encoding: "utf8", timeout: 3000, maxBuffer: 1024 * 1024 });
+  const pipe = processEnv.stdout?.match(/(?:^| )CODEX_APP_TOOLS_PIPE_PATH=([^ \n]*)/)?.[1];
+  const encoded = processEnv.stdout?.match(/(?:^| )CODEX_TASK_WORKSPACE_VERIFYING_IDENTITY=([^ \n]*)/)?.[1];
+  if (processEnv.status !== 0 || pipe !== target.socketPath || !encoded || !/^[A-Za-z0-9+/]{40,200}={0,2}$/.test(encoded)) throw failure("The selected Desktop has no verifiable project API identity.");
+  let key;
+  try { key = createPublicKey({ key: Buffer.from(encoded, "base64"), format: "der", type: "spki" }); } catch { throw failure("Invalid Desktop project API verification key."); }
+  if (key.asymmetricKeyType !== "ed25519") throw failure("Unsupported Desktop project API signature.");
+  return { ...selected, endpoint: target, key, key_id: sha(key.export({ format: "der", type: "spki" })) };
+}
+export function verifyProjectReply(reply, method, params, key) {
+  if (!["taskProject/list", "taskProject/assign"].includes(method) || typeof reply?.payload !== "string" || Buffer.byteLength(reply.payload) > 8 * 1024 * 1024
+    || typeof reply.signature !== "string" || !/^[A-Za-z0-9+/]{86}==$/.test(reply.signature)) throw failure("Invalid signed project response.", "DESKTOP_CLOUD_PROJECT_PROTOCOL");
+  let body, valid = false;
+  try { valid = verify(null, Buffer.from(reply.payload), key, Buffer.from(reply.signature, "base64")); body = JSON.parse(reply.payload); } catch {}
+  if (!valid || body?.domain !== `codex.${method.replace("/", ".")}.v1` || !isDeepStrictEqual(body.request, params)) throw failure("Project response signature or request binding did not match.", "DESKTOP_CLOUD_PROJECT_PROTOCOL");
+  return method === "taskProject/list" ? body.catalog : body.project;
+}
+async function current(api, discover = discoverRuntime) {
+  const next = await discover();
+  if (next.paths.home !== api.paths.home || next.paths.socket !== api.paths.socket || next.state.pid !== api.state.pid || next.state.instance !== api.state.instance) throw failure("Desktop changed during the operation. Inspect the receipt before retrying.", "DESKTOP_CLOUD_PROJECT_BINDING_CHANGED");
+  await inspectNativeEndpoint(api.endpoint.socketPath, api.endpoint.fingerprint);
+}
+export function validateProjectCatalog(catalog, environmentId) {
+  if (catalog?.environmentId !== environmentId || !Array.isArray(catalog.projects) || catalog.projects.length > 10000) throw failure("Invalid project catalog environment.", "DESKTOP_CLOUD_PROJECT_PROTOCOL");
+  const ids = new Set();
+  for (const row of catalog.projects) {
+    if (typeof row?.projectId !== "string" || !row.projectId || row.projectId.length > 400 || ids.has(row.projectId) || typeof row.name !== "string" || !row.name.trim()
+      || !Array.isArray(row.rootPaths) || !row.rootPaths.length || row.rootPaths.some(root => typeof root !== "string" || root.includes("\0") || !(path.isAbsolute(root) || path.win32.isAbsolute(root)))) throw failure("Invalid project catalog entry.", "DESKTOP_CLOUD_PROJECT_PROTOCOL");
+    ids.add(row.projectId);
+  }
+  return catalog.projects.map(row => ({ project_id: row.projectId, name: row.name, roots: [...row.rootPaths] }));
+}
+async function catalogOnApi(api, environmentId, { call = nativeRpc, check = current } = {}) {
+  await check(api);
+  const params = { environmentId, nonce: randomBytes(32).toString("hex") };
+  let response;
+  try { response = await call(api.endpoint, { jsonrpc: "2.0", id: randomUUID(), method: "taskProject/list", params }); }
+  catch { throw failure("Desktop did not authorize project assignment for this task's actual environment. This API requires its own ready Desktop executor; the environment ID is never substituted."); }
+  const rows = validateProjectCatalog(verifyProjectReply(response, "taskProject/list", params, api.key), environmentId);
+  await check(api); return rows;
+}
+async function targetEnvironment(client, id) {
+  const { thread } = await client.request("thread/read", { threadId: id });
+  if (thread?.id !== id || !Array.isArray(thread.environments) || thread.environments.length !== 1 || typeof thread.environments[0]?.environmentId !== "string" || !thread.environments[0].environmentId) throw failure("Cannot verify the Cloud task's environment.", "DESKTOP_CLOUD_PROJECT_PROTOCOL");
+  return thread.environments[0].environmentId;
+}
+export async function readDesktopProjectState(home, threadInput) {
+  const id = desktopCloudUuid(threadInput), file = await open(path.join(home, ".codex-global-state.json"), constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.uid !== process.getuid() || (info.mode & 0o022) || info.size > 16 * 1024 * 1024) throw failure("Unsafe Desktop project state.", "DESKTOP_CLOUD_PROJECT_STATE_UNSAFE");
+    const bytes = Buffer.alloc(16 * 1024 * 1024 + 1), { bytesRead } = await file.read(bytes, 0, bytes.length, 0); if (bytesRead > 16 * 1024 * 1024) throw failure("Desktop project state exceeded its limit.");
+    const state = JSON.parse(bytes.subarray(0, bytesRead).toString("utf8")), assignment = state["thread-project-assignments"]?.[id];
+    if (assignment != null && (typeof assignment.projectKind !== "string" || typeof assignment.projectId !== "string" || !assignment.projectId || assignment.projectId.length > 400)) throw failure("Invalid Desktop project membership record.", "DESKTOP_CLOUD_PROJECT_PROTOCOL");
+    return { assignment: assignment ?? null, host_id: state["thread-project-membership-host-ids"]?.[id] ?? null,
+      projectless: Array.isArray(state["projectless-thread-ids"]) && state["projectless-thread-ids"].includes(id) };
+  } finally { await file.close(); }
+}
+export async function desktopCloudProjectDoctor(target, selector, { connect = connectDesktopCloud, discoverApi = discoverProjectApi, catalog = catalogOnApi,
+  readState = readDesktopProjectState, projects = listProjects } = {}) {
+  const id = desktopCloudId(target); let client, api;
+  const report = { assignment_api: { status: "unavailable" }, membership: { status: "unverified" } };
+  try {
+    client = await connect(); const environment = await targetEnvironment(client, id);
+    try { api = await discoverApi(); } catch (error) { report.assignment_api.reason_code = error.code ?? "DESKTOP_CLOUD_PROJECT_UNAVAILABLE"; return report; }
+    let rows;
+    try { rows = await catalog(api, environment); report.assignment_api.status = "available"; }
+    catch (error) { if (error.code === "DESKTOP_CLOUD_PROJECT_PROTOCOL" || error.code === "DESKTOP_CLOUD_PROJECT_BINDING_CHANGED") throw error; report.assignment_api.reason_code = error.code ?? "DESKTOP_CLOUD_PROJECT_UNAVAILABLE"; report.assignment_api.reason = "The actual Cloud environment was not accepted by Desktop's executor-bound API."; }
+    let selected;
+    if (selector !== undefined) {
+      const inventory = rows ?? (await projects()).flatMap(row => (row.desktop_project_ids ?? []).map(legacy => ({ ...row, canonical_project_id: row.project_id, project_id: legacy })));
+      const matches = inventory.filter(row => row.project_id === selector || row.canonical_project_id === selector || row.name === selector);
+      if (matches.length !== 1) throw failure("Select exactly one Desktop project ID or exact name.", "PROJECT_NOT_FOUND"); selected = matches[0];
+      report.selected_project = selected;
+    }
+    const state = await readState(api.paths.home, id);
+    report.membership = { status: state.assignment?.projectKind === "local" ? (state.host_id === "durable" ? "registered" : "recorded_host_unverified") : state.projectless ? "projectless" : "source_unknown",
+      project_id: state.assignment?.projectId ?? null, host_id: state.host_id, source: "read-only-desktop-profile-state" };
+    if (selected) report.membership.matches_selected_project = state.assignment?.projectKind === "local" && state.assignment.projectId === selected.project_id && state.host_id === "durable";
+    return report;
+  } finally { try { client?.close(); } catch { /* Preserve diagnostics. */ } }
+}
+export async function assignDesktopCloudProject(target, selector, { connect = connectDesktopCloud, discoverApi = discoverProjectApi, catalog = catalogOnApi,
+  call = nativeRpc, check = current, readState = readDesktopProjectState, ...storage } = {}) {
+  const id = desktopCloudId(target);
+  if (typeof selector !== "string" || !selector.trim()) throw failure("--project is required.", "PROJECT_REQUIRED");
+  return withStoreLock(`desktop-cloud-project-${id}`, async () => {
+    if ((await listRecords("desktop-cloud-projects", storage)).some(row => row.thread_id === id && row.delivery_status === "unknown")) throw failure("An earlier assignment is unknown. Inspect its receipt; do not replay it.", "DESKTOP_CLOUD_PROJECT_PENDING");
+    let client, receipt, api, dispatching = false;
+    try {
+      client = await connect(); const environmentId = await targetEnvironment(client, id); api = await discoverApi();
+      if (api.paths.home !== (storage.home ?? codexHome())) throw failure("Desktop project profile does not match the CLI profile.", "DESKTOP_CLOUD_PROJECT_BINDING_CHANGED");
+      const rows = await catalog(api, environmentId), matches = rows.filter(row => row.project_id === selector || row.name === selector);
+      if (matches.length !== 1) throw failure("Select one project returned by the signed catalog.", "PROJECT_NOT_FOUND");
+      const selected = matches[0], attempt = randomUUID();
+      receipt = { schema: 1, type: "desktop-cloud-project", attempt_id: attempt, thread_id: id, environment_id: environmentId, project_id: selected.project_id,
+        delivery_status: "not_sent", verification_status: "unverified", receipt_path: storePath("desktop-cloud-projects", attempt, storage.home) };
+      await writeRecord("desktop-cloud-projects", attempt, receipt, storage); await check(api);
+      if (await targetEnvironment(client, id) !== environmentId) throw failure("Task environment changed before assignment.", "DESKTOP_CLOUD_PROJECT_BINDING_CHANGED");
+      const params = { environmentId, projectId: selected.project_id, threadId: desktopCloudUuid(id), nonce: randomBytes(32).toString("hex") };
+      receipt.delivery_status = "unknown"; await writeRecord("desktop-cloud-projects", attempt, receipt, storage); dispatching = true;
+      const response = await call(api.endpoint, { jsonrpc: "2.0", id: randomUUID(), method: "taskProject/assign", params });
+      const assigned = verifyProjectReply(response, "taskProject/assign", params, api.key);
+      if (!isDeepStrictEqual(assigned, { environmentId, projectId: selected.project_id, threadId: desktopCloudUuid(id) })) throw failure("Assignment response target did not match.", "DESKTOP_CLOUD_PROJECT_PROTOCOL", true);
+      receipt.delivery_status = "accepted"; receipt.proof_sha256 = sha(response.payload);
+      await writeRecord("desktop-cloud-projects", attempt, receipt, storage); await check(api);
+      const stored = await readState(api.paths.home, id);
+      receipt.verification_status = stored.assignment?.projectKind === "local" && stored.assignment.projectId === selected.project_id && stored.host_id === "durable" ? "verified" : "not_observed";
+      await writeRecord("desktop-cloud-projects", attempt, receipt, storage); return receipt;
+    } catch (error) {
+      if (receipt) {
+        if (receipt.delivery_status !== "accepted") receipt.delivery_status = dispatching && ![-32601, -32602].includes(error.rpcCode) ? "unknown" : "not_sent";
+        try { await writeRecord("desktop-cloud-projects", receipt.attempt_id, { ...receipt, error_code: error.code ?? "DESKTOP_CLOUD_PROJECT_UNAVAILABLE" }, storage); } catch { error.receipt_update_required = true; }
+        Object.assign(error, { attempt_id: receipt.attempt_id, receipt_path: receipt.receipt_path, delivery_status: receipt.delivery_status, uncertain: receipt.delivery_status === "unknown" });
+      }
+      throw error;
+    } finally { try { client?.close(); } catch { /* Preserve diagnostics. */ } }
+  }, storage);
+}
+export async function desktopCloudProjectReceipt(attempt, storage = {}) {
+  if (typeof attempt !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(attempt)) throw failure("Invalid assignment attempt ID.");
+  const row = await readRecord("desktop-cloud-projects", attempt, storage);
+  if (!row || row.type !== "desktop-cloud-project" || row.attempt_id !== attempt) throw failure("Assignment receipt not found."); return row;
+}

package/src/desktop-cloud.mjs

@@ -0,0 +1,98 @@
+import { createHash, randomUUID } from "node:crypto";
+import { connectDesktopCloud, desktopCloudEnvironments } from "./desktop-cloud-api.mjs";
+import { desktopCloudId, desktopCloudLink } from "./desktop-cloud-id.mjs";
+import { fetchThread } from "./observe.mjs";
+import { readRecord, writeRecord, storePath, withStoreLock, listRecords } from "./store.mjs";
+const failure = (message, code = "DESKTOP_CLOUD_OPTIONS_INVALID", uncertain = false) => Object.assign(new Error(message), { code, uncertain });
+const hash = value => createHash("sha256").update(value).digest("hex");
+export async function desktopCloudReceipt(attempt, storage = {}) {
+  if (!/^[a-f0-9-]{36}$/.test(attempt ?? "")) throw failure("Invalid creation attempt ID.");
+  const receipt = await readRecord("desktop-cloud-creations", attempt, storage);
+  if (!receipt || receipt.attempt_id !== attempt) throw failure("Creation receipt not found.", "DESKTOP_CLOUD_CREATION_RECEIPT_NOT_FOUND");
+  return receipt;
+}
+export async function createDesktopCloudTask(selector, prompt, options = {}, { environments = desktopCloudEnvironments, connect = connectDesktopCloud, ...storage } = {}) {
+  if (options.project !== undefined) throw failure("Creation cannot currently register a Desktop project for a newly allocated Cloud environment. No chat was created. Use doctor --thread TARGET --project PROJECT to check an existing task's executor-bound assignment API.", "DESKTOP_CLOUD_PROJECT_UNAVAILABLE");
+  if (typeof selector !== "string" || !selector.trim() || typeof prompt !== "string" || !prompt.trim()) throw failure("An --environment ID or exact name and initial instruction are required.");
+  if (options.title !== undefined && (typeof options.title !== "string" || !options.title.trim() || options.title.length > 1000)) throw failure("Invalid --title.");
+  const matches = (await environments()).environments.filter(row => row.id === selector || row.name === selector);
+  if (matches.length !== 1) throw failure("Select exactly one accessible environment configuration.");
+  const selected = matches[0], attempt = randomUUID();
+  let client, receipt = { schema: 1, attempt_id: attempt, environment_config_id: selected.id, environment_name: selected.name, connection_mode: "desktop-cloud",
+    project_membership: "not_requested", creation_status: "not_created", delivery_status: "not_sent", sent: false, prompt_sha256: hash(prompt), dry_run: !!options.dryRun }, creating = false;
+  if (options.dryRun) return receipt;
+  receipt.receipt_path = storePath("desktop-cloud-creations", attempt, storage.home);
+  const save = () => writeRecord("desktop-cloud-creations", attempt, receipt, storage);
+  try {
+    client = await connect();
+    const models = await client.request("model/list", { limit: 100 });
+    const defaults = models?.data?.filter(row => row.isDefault === true);
+    if (defaults?.length !== 1 || typeof defaults[0].model !== "string") throw failure("Cloud did not identify one default model.");
+    receipt.creation_status = "dispatching"; await save(); creating = true;
+    const result = await client.request("thread/start", { model: defaults[0].model, serviceName: "codex_cloud", threadSource: "user", pluginsMcp: { productSku: "codex" },
+      config: { "features.mcp_app_ui": true }, environments: [{ environmentConfigId: selected.id }], deferredEnvironment: true, ephemeral: false }, { mutation: true });
+    receipt = { ...receipt, creation_status: "created", thread_id: desktopCloudId(result.thread.id), deep_link: desktopCloudLink(result.thread.id) }; creating = false; await save();
+    if (options.title) await client.request("thread/name/set", { threadId: receipt.thread_id, name: options.title }, { mutation: true });
+    const { sendTrackedMessage } = await import("./journal.mjs");
+    const sent = await sendTrackedMessage(receipt.thread_id, prompt, { newTurn: true, connection: "desktop-cloud" }, { ...storage,
+      send: (target, text, settings) => sendDesktopCloudInput(target, text, settings, { ...storage, connect: async () => ({ request: (...args) => client.request(...args), close() {} }) }) });
+    receipt = { ...receipt, ...sent }; await save(); return receipt;
+  } catch (error) {
+    if (creating) receipt.creation_status = error.uncertain !== false ? "unknown" : "not_created";
+    if (error.delivery_status) Object.assign(receipt, { delivery_status: error.delivery_status, sent: error.sent });
+    if (error.message_id) Object.assign(receipt, { message_id: error.message_id, client_message_id: error.client_message_id });
+    receipt.error_code = error.code ?? "DESKTOP_CLOUD_FAILED";
+    try { await save(); } catch { error.receipt_update_required = true; }
+    Object.assign(error, { execution_environment: "cloud", creation_status: receipt.creation_status, thread_id: receipt.thread_id, attempt_id: attempt, receipt_path: receipt.receipt_path, sent: receipt.sent, delivery_status: receipt.delivery_status }); throw error;
+  } finally { try { client?.close(); } catch { receipt.runtime_cleanup_required = true; } }
+}
+export async function sendDesktopCloudInput(target, text, { dryRun = false, newTurn = false, clientMessageId = randomUUID(), beforeSend } = {}, { connect = connectDesktopCloud, ...storage } = {}) {
+  const id = desktopCloudId(target);
+  if (typeof text !== "string" || !text.trim()) throw failure("A non-empty message is required.");
+  const plan = { thread_id: id, deep_link: desktopCloudLink(id), client_message_id: clientMessageId, backend: "desktop-cloud", connection_mode: "desktop-cloud", delivery_action: newTurn ? "new-turn" : "steer", dry_run: dryRun, message_characters: [...text].length };
+  if (dryRun) return { ...plan, sent: false, delivery_status: "not_sent" };
+  return withStoreLock(`desktop-cloud-send-${id}`, async () => {
+    const pending = (await listRecords("desktop-cloud-sends", storage)).find(row => row.thread_id === id && row.delivery_status === "unknown");
+    if (pending) throw failure("An earlier Desktop Cloud delivery is unknown. Inspect history; it must not be replayed automatically.", "DESKTOP_CLOUD_DELIVERY_PENDING");
+    let client, dispatching = false, receipt = { ...plan, prompt_sha256: hash(text), sent: false, delivery_status: "not_sent" };
+    const save = () => writeRecord("desktop-cloud-sends", clientMessageId, receipt, storage);
+    try {
+      client = await connect();
+      const thread = await fetchThread(client, id), active = thread.turns.filter(turn => turn.status === "inProgress");
+      if (newTurn ? thread.status?.type !== "idle" || active.length !== 0 : active.length !== 1) throw failure("The task state does not match the requested send. Read it again; idle continuation requires --new-turn.", "STALE_OBSERVATION");
+      const environments = thread.environments;
+      if (!Array.isArray(environments) || environments.length !== 1 || typeof environments[0].environmentId !== "string" || !environments[0].environmentId.startsWith("ccarenv_") || typeof environments[0].environmentConfigId !== "string") throw failure("Cannot verify the task's Cloud environment.");
+      await beforeSend?.(thread, client);
+      receipt.delivery_status = "unknown"; await save(); dispatching = true;
+      const params = { threadId: id, input: [{ type: "text", text, text_elements: [] }], clientUserMessageId: clientMessageId };
+      const result = await client.request(newTurn ? "turn/start" : "turn/steer", newTurn ? { ...params, environments, deferredEnvironment: true } : { ...params, expectedTurnId: active[0].id }, { mutation: true });
+      const turnId = newTurn ? result?.turn?.id : result?.turnId;
+      if (typeof turnId !== "string" || (!newTurn && turnId !== active[0].id)) throw failure("Cloud did not confirm the expected turn. Inspect history before another send.", "DESKTOP_CLOUD_PROTOCOL_ERROR", true);
+      receipt = { ...receipt, turn_id: turnId, sent: true, delivery_status: "accepted" };
+      try { await save(); } catch { receipt.receipt_update_required = true; } return receipt;
+    } catch (error) {
+      const unknown = dispatching && error.uncertain !== false;
+      receipt = { ...receipt, sent: unknown ? null : false, delivery_status: unknown ? "unknown" : "not_sent", error_code: error.code ?? "DESKTOP_CLOUD_FAILED" };
+      try { await save(); } catch { error.receipt_update_required = true; }
+      Object.assign(error, { uncertain: unknown, sent: receipt.sent, delivery_status: receipt.delivery_status }); throw error;
+    } finally { try { client?.close(); } catch { receipt.runtime_cleanup_required = true; } }
+  }, storage);
+}
+export async function listDesktopCloudTasks(options = {}, { connect = connectDesktopCloud } = {}) {
+  if (!Number.isInteger(options.limit ?? 20) || options.limit < 1 || options.limit > 100) throw failure("--limit must be 1..100.");
+  const client = await connect();
+  try { const data = await client.request("thread/list", { limit: options.limit ?? 20, ...(options.cursor ? { cursor: options.cursor } : {}) });
+    if (!Array.isArray(data?.data)) throw failure("Invalid task inventory.");
+    return { threads: data.data.map(row => ({ thread_id: desktopCloudId(`durable_${row.id}`), deep_link: desktopCloudLink(`durable_${row.id}`), title: row.name ?? null, status: row.status })), next_cursor: data.nextCursor ?? null };
+  } finally { try { client.close(); } catch { /* Do not mask the read result. */ } }
+}
+
+export async function confirmDesktopCloudDelivery(entry, verification, storage = {}) {
+  if (verification.status !== "stored" || entry.delivery_status === "not_sent") return;
+  const id = desktopCloudId(entry.thread_id);
+  return withStoreLock(`desktop-cloud-send-${id}`, async () => {
+    const receipt = await readRecord("desktop-cloud-sends", entry.client_message_id, storage);
+    if (!receipt || receipt.thread_id !== id || receipt.prompt_sha256 !== hash(entry.wire_text) || receipt.delivery_status === "not_sent") return;
+    await writeRecord("desktop-cloud-sends", entry.client_message_id, { ...receipt, delivery_status: "accepted", sent: true, turn_id: verification.turn_id, delivery_verification: "stored" }, storage);
+  }, storage);
+}

package/src/desktop.mjs

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { threadComposerDeepLink, threadDeepLink } from "./thread-id.mjs";
+import { threadComposerDeepLink, threadDeepLink, parseThreadTarget } from "./thread-id.mjs";
 import { readDesktopSettings } from "./settings.mjs";
+import { targetHost, remoteReadOnly } from "./target.mjs";
 
 const APP_PATH = "/Applications/ChatGPT.app";
 const APP_BUNDLE_ID = "com.openai.codex";
@@ -179,6 +180,7 @@ export function sendDesktopMessage(
   message,
   { dryRun = false, waitMs = 1500, newTurn = false, keepFocus = false } = {},
 ) {
+  if ((parseThreadTarget(threadId).hostId ?? targetHost()) !== "local") throw remoteReadOnly();
   if (message.trim() === "") throw new Error("Message must not be empty.");
   validateWaitMs(waitMs);
 

package/src/directive.mjs

@@ -21,7 +21,7 @@ export async function prepareDirective(threadId, body, options, id, storage = {}
     ...(concern ? { finding_id: concern.id, finding_revision: concern.revision } : {}), ...(supervisor ? { supervisor_id: supervisor } : {}) };
   const lines = [`[codexteer ${id}]`, `送信者: ${metadata.source}`, `種類: ${kindLabels[metadata.kind]}`];
   for (const ref of refs) lines.push(`根拠: ${JSON.stringify(ref.ref)}${ref.sha256 ? ` (sha256:${ref.sha256})` : " (参照URL)"}`);
-  if (observed) lines.push(`観測対象ターン: ${observed.active_turn_id ?? "停止中"}`);
+  if (observed) lines.push(`観測対象ターン: ${observed.active_turn_id ?? "未確定"}`);
   if (supersedes) lines.push(`置き換える指示: ${supersedes}。この指示を以後の方針として扱ってください。`);
   if (retracts) lines.push(`撤回する指示: ${retracts}。以後の方針から除外してください。`);
   if (expiresAt) lines.push(`有効期限: ${expiresAt}`);
@@ -34,7 +34,10 @@ export async function prepareDirective(threadId, body, options, id, storage = {}
       else {
         if (thread.turns?.some(t => t.itemsView && t.itemsView !== "full") || !thread.turns?.length) thread = await fetchThread(client, threadId);
         const current = threadSnapshot(thread);
-        if (current.user_revision !== observed.user_revision || current.state.active_turn_id !== observed.active_turn_id) throw Object.assign(new Error("New user input or a different turn was observed. Read the task again before sending."), { code: "STALE_OBSERVATION" });
+        const latestChanged = observed.latest_turn_id !== undefined && observed.latest_turn_id !== (thread.turns?.at(-1)?.id ?? null);
+        // Older v1 cursors cannot distinguish two ambiguous active snapshots.
+        const unpinned = observed.latest_turn_id === undefined && thread.historyMode === "paginated" && thread.turns.filter(t => t.status === "inProgress").length > 1;
+        if (latestChanged || unpinned || current.user_revision !== observed.user_revision || current.state.active_turn_id !== observed.active_turn_id) throw Object.assign(new Error("New user input or a different turn was observed, or the old cursor cannot identify the latest turn. Read the task again before sending."), { code: "STALE_OBSERVATION" });
       }
     }
     await verifyEvidence(refs);

package/src/distribution.mjs

@@ -38,7 +38,7 @@ async function checkAncestors(directory) {
   }
 }
 
-async function resolveHome(home) {
+export async function prepareCodexHome(home) {
   let existing = path.resolve(home), canonical;
   const missing = [];
   while (true) {
@@ -53,6 +53,8 @@ async function resolveHome(home) {
     canonical = path.join(canonical, part);
     await ownedDirectory(canonical, true);
   }
+  const homeInfo = await lstat(canonical);
+  if (!homeInfo.isDirectory() || homeInfo.uid !== process.getuid() || (homeInfo.mode & 0o7022)) throw failure("CODEX_HOME must be an owner-controlled directory.");
   return canonical;
 }
 
@@ -86,8 +88,8 @@ export async function describeDistribution(root = PACKAGE_ROOT) {
   root = await realpath(root);
   await checkAncestors(root);
   check(await lstat(root), true, false);
-  const names = ["package.json", "LICENSE", "bin/codexteer.mjs", "bin/codexteer-wrapper.mjs", "assets/send-pururu.wav",
-    "scripts/send.applescript", "scripts/inspect.applescript", "scripts/accessibility.applescript"];
+  const names = ["package.json", "LICENSE", "bin/codexteer.mjs", "bin/codexteer-wrapper.mjs", "bin/codexteer-update.mjs", "assets/send-pururu.wav", "assets/remote-device-key.swift",
+    "scripts/send.applescript", "scripts/inspect.applescript", "scripts/accessibility.applescript", "scripts/update-desktop.applescript"];
   for (const directory of ["bin", "assets", "scripts", "src", "node_modules", "node_modules/ws", "node_modules/ws/lib"]) {
     check(await lstat(path.join(root, directory)), true, false);
   }
@@ -150,9 +152,7 @@ export async function prepareDeployment(home, { sourceRoot = PACKAGE_ROOT } = {}
   const distribution = await describeDistribution(sourceRoot);
   // CODEX_HOME may itself be a user-configured symlink; only its canonical
   // owner-writable directory is accepted. Never follow links below that root.
-  const canonicalHome = await resolveHome(home);
-  const homeInfo = await lstat(canonicalHome);
-  if (!homeInfo.isDirectory() || homeInfo.uid !== process.getuid() || (homeInfo.mode & 0o7022)) throw failure("CODEX_HOME must be an owner-controlled directory.");
+  const canonicalHome = await prepareCodexHome(home);
   const stateRoot = path.join(canonicalHome, "codex-steer"), root = path.join(stateRoot, "runtimes");
   await ownedDirectory(stateRoot, true); await ownedDirectory(root, true);
   const target = path.join(root, distribution.id), lock = path.join(root, `.install-${distribution.id}`);

package/src/evidence.mjs

@@ -2,8 +2,11 @@ import { stat, realpath } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { createHash } from "node:crypto";
 import path from "node:path";
+import { targetHost } from "./target.mjs";
+import { remoteFingerprintFile } from "./remote-io.mjs";
 
 export async function fingerprintFile(input) {
+  if (targetHost() !== "local") return remoteFingerprintFile(input);
   const ref = path.resolve(input), canonical = await realpath(ref), before = await stat(canonical);
   if (!before.isFile()) throw new Error("Evidence must be a file or an http(s)/codex URL.");
   const hash = createHash("sha256");

package/src/findings.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { normalizeThreadId } from "./thread-id.mjs";
+import { normalizeTaskId } from "./task-id.mjs";
 import { readRecord, writeRecord, listRecords, withStoreLock } from "./store.mjs";
 import { collectEvidence } from "./evidence.mjs";
 import { decodeCursor, digest } from "./observe.mjs";
@@ -16,7 +16,7 @@ const text = (value, label, max = 8000) => {
 const contextHash = record => digest({ condition: record.condition, evidence: record.evidence });
 
 export async function getFinding(threadInput, id, storage = {}) {
-  const threadId = normalizeThreadId(threadInput), record = await readRecord("findings", id, storage);
+  const threadId = normalizeTaskId(threadInput), record = await readRecord("findings", id, storage);
   if (!record || record.schema !== 1 || record.id !== id || record.thread_id !== threadId) throw failure("Finding not found for this task.", "FINDING_NOT_FOUND");
   if (!Number.isSafeInteger(record.revision) || record.revision < 1 || !["open", "resolved", "dismissed"].includes(record.disposition)
     || !Array.isArray(record.evidence) || typeof record.condition !== "string" || !ratings.includes(record.evaluation?.rating)) throw failure("Invalid finding record.", "FINDING_INVALID");
@@ -30,7 +30,7 @@ export async function findingMessages(record, storage = {}) {
 }
 
 export async function createFinding(threadInput, { key, title, condition, evidence = [], basedOn, ...storage }) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   if (typeof key !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,150}$/.test(key)) throw failure("--key requires a stable short identifier for this concern.", "FINDING_INVALID");
   text(title, "--title", 240); text(condition, "--condition");
   const refs = await collectEvidence(evidence), observed = basedOn ? decodeCursor(basedOn, threadId) : null;
@@ -77,7 +77,7 @@ export async function findingStatus(threadInput, id, storage = {}) {
 }
 
 export async function listFindings(threadInput, { all = false, limit = 50, ...storage } = {}) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   if (!Number.isInteger(limit) || limit < 1 || limit > 1000) throw failure("--limit must be between 1 and 1000.", "FINDING_INVALID");
   const records = (await listRecords("findings", storage)).filter(record => record?.thread_id === threadId).sort((a, b) => b.updated_at.localeCompare(a.updated_at));
   // Recheck closed resolutions too: changed inputs make them unresolved again.
@@ -90,7 +90,7 @@ export async function listFindings(threadInput, { all = false, limit = 50, ...st
 }
 
 async function changeFinding(threadInput, id, update, storage) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   return withStoreLock(`message-${threadId}`, async () => {
     const record = await getFinding(threadId, id, storage);
     const updated = { ...await update(record), updated_at: new Date().toISOString() };
@@ -124,7 +124,7 @@ export async function dismissFinding(threadInput, id, { reason, ...storage }) {
 }
 
 export async function reopenFinding(threadInput, id, { reason, evidence, basedOn, condition, ...storage }) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   text(reason, "--reason"); if (condition !== undefined) text(condition, "--condition");
   const refs = evidence === undefined ? undefined : await collectEvidence(evidence);
   const observed = basedOn === undefined ? undefined : decodeCursor(basedOn, threadId);
@@ -145,7 +145,7 @@ export async function evaluateFinding(threadInput, id, { rating, reason, ...stor
 }
 
 export async function findingStats(threadInput, storage = {}) {
-  const threadId = normalizeThreadId(threadInput), records = (await listRecords("findings", storage)).filter(record => record?.thread_id === threadId);
+  const threadId = normalizeTaskId(threadInput), records = (await listRecords("findings", storage)).filter(record => record?.thread_id === threadId);
   const counts = Object.fromEntries(ratings.map(rating => [rating, 0]));
   let sent = 0;
   for (const entry of records) {