codexteer 0.17.0 → 0.18.1

package/src/store.mjs

@@ -1,13 +1,15 @@
 import { lstat, mkdir, readFile, writeFile, rename, rm, readdir, link } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { codexHome, isAlive } from "./runtime.mjs";
+import { hostNamespace, hostFields } from "./target.mjs";
 
 const valid = value => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,150}$/.test(value);
 // The persisted namespace predates the codexteer rename; keep existing records.
 export function storePath(bucket, id, home = codexHome()) {
   if (!valid(bucket) || (id != null && !valid(id))) throw new Error("Invalid local record identifier.");
-  return path.join(home, "codex-steer", bucket, ...(id == null ? [] : [`${id}.json`]));
+  const namespace = hostNamespace();
+  return path.join(home, "codex-steer", ...(namespace ? ["hosts", namespace] : []), bucket, ...(id == null ? [] : [`${id}.json`]));
 }
 
 async function owned(file, directory = false) {
@@ -17,7 +19,8 @@ async function owned(file, directory = false) {
 
 async function directory(bucket, home, create = false) {
   const root = path.join(home, "codex-steer"), target = storePath(bucket, null, home);
-  for (const p of [root, target]) {
+  const namespace = hostNamespace();
+  for (const p of [root, ...(namespace ? [path.join(root, "hosts"), path.join(root, "hosts", namespace)] : []), target]) {
     if (create) await mkdir(p, { mode: 0o700 }).catch(e => { if (e.code !== "EEXIST") throw e; });
     await owned(p, true);
   }
@@ -36,7 +39,7 @@ export async function writeRecord(bucket, id, data, { home = codexHome() } = {})
   await directory(bucket, home, true);
   const target = storePath(bucket, id, home), temp = `${target}.${randomUUID()}.tmp`;
   await owned(target).catch(e => { if (e.code !== "ENOENT") throw e; });
-  try { await writeFile(temp, JSON.stringify(data) + "\n", { mode: 0o600, flag: "wx" }); await rename(temp, target); }
+  try { await writeFile(temp, JSON.stringify({ ...data, ...hostFields() }) + "\n", { mode: 0o600, flag: "wx" }); await rename(temp, target); }
   finally { await rm(temp, { force: true }); }
 }
 
@@ -48,22 +51,31 @@ export async function listRecords(bucket, options = {}) {
 }
 
 export async function withStoreLock(key, fn, { home = codexHome() } = {}) {
-  await directory("locks", home, true);
-  const file = storePath("locks", key, home), token = randomUUID(), temp = `${file}.${token}.tmp`;
+  return withRecordLock("locks", key, fn, { home });
+}
+
+async function withRecordLock(bucket, key, fn, { home }) {
+  await directory(bucket, home, true);
+  const file = storePath(bucket, key, home), token = randomUUID(), temp = `${file}.${token}.tmp`;
   await writeFile(temp, JSON.stringify({ token, pid: process.pid }), { mode: 0o600, flag: "wx" });
   let acquired = false;
   let outcome;
   try {
     for (let attempt = 0; attempt < 2; attempt++) {
       try { await link(temp, file); acquired = true; break; } catch (e) { if (e.code !== "EEXIST") throw e; }
-      const old = await readRecord("locks", key, { home });
+      const old = await readRecord(bucket, key, { home });
       if (old && !isAlive(old.pid)) {
-        const recovery = `${file}.recover`;
-        try { await mkdir(recovery, { mode: 0o700 }); } catch (e) { if (e.code !== "EEXIST") throw e; break; }
-        try {
-          const current = await readRecord("locks", key, { home });
+        // Serialize deletion of this generation, including recovery of a crashed
+        // recoverer. Each nested lock has an atomically published PID + token.
+        // A finite chain of dead owners ends at an absent recovery lock.
+        // Legacy .recover directories have no owner and are unsupported/inert.
+        // Stop all old-version operations (including saved supervisor CLIs)
+        // sharing this CODEX_HOME before using this recovery protocol.
+        const recoveryKey = createHash("sha256").update(String(old.token)).digest("hex");
+        await withRecordLock("lock-recovery", recoveryKey, async () => {
+          const current = await readRecord(bucket, key, { home });
           if (current?.token === old.token && !isAlive(current.pid)) await rm(file);
-        } finally { await rm(recovery, { recursive: true }); }
+        }, { home });
       } else break;
     }
     if (!acquired) throw Object.assign(new Error("Another operation owns this local record. Retry after it finishes."), { code: "RECORD_BUSY" });
@@ -71,7 +83,7 @@ export async function withStoreLock(key, fn, { home = codexHome() } = {}) {
     return outcome;
   } finally {
     try {
-      if (acquired && (await readRecord("locks", key, { home }))?.token === token) await rm(file);
+      if (acquired && (await readRecord(bucket, key, { home }))?.token === token) await rm(file);
       await rm(temp, { force: true });
     } catch { if (outcome && typeof outcome === "object") outcome.state_cleanup_required = true; }
   }

package/src/supervise.mjs

@@ -1,58 +1,50 @@
-import { spawn } from "node:child_process";
-import { once } from "node:events";
-import { constants } from "node:os";
-import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { randomUUID } from "node:crypto";
-import { prepareCodexHome, prepareDeployment } from "./distribution.mjs";
-import { normalizeThreadId } from "./thread-id.mjs";
+import { prepareCodexHome } from "./distribution.mjs";
+import { parseThreadTarget } from "./thread-id.mjs";
+import { normalizeTaskId, taskConnection } from "./task-id.mjs";
 import { codexHome } from "./runtime.mjs";
 import { supervisorPrompt as pathSupervisorPrompt, validateSupervisionPolicy } from "./prompt.mjs";
 import { registerSupervisor, controlSupervisor } from "./supervision.mjs";
 import { connectionMode } from "./connection.mjs";
+import { preparePromptCommand, shellArgument, SUPERVISOR_AGENTS } from "./prompt-command.mjs";
+import { launchAgent } from "./agent-launch.mjs";
+import { targetHost, targetContext, hostFields, remoteTransport } from "./target.mjs";
 
-export const SUPERVISOR_AGENTS = ["claude", "codex"];
-
-function shellArgument(value) {
-  if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(value)) {
-    throw Object.assign(new Error("Cannot generate supervision commands from a path containing control characters. Use a path without them and generate the prompt again."), { code: "SUPERVISION_PATH_UNSAFE" });
-  }
-  return `'${value.replaceAll("'", "'\\''")}'`;
-}
+export { SUPERVISOR_AGENTS };
 
 export async function prepareSupervisorPrompt(threadInput, policy, { agent = "claude", connection = "shared", usePathCli = false } = {}) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
+  connection = taskConnection(threadId, connection);
   validateSupervisionPolicy(policy);
   connectionMode(connection);
   if (!SUPERVISOR_AGENTS.includes(agent)) throw new Error("--agent must be claude or codex.");
-  const supervisor = { session_id: randomUUID(), owner: agent, connection };
-  const sessionOptions = `--supervisor ${shellArgument(supervisor.session_id)} --connection ${connection}`;
+  const supervisor = { session_id: randomUUID(), owner: agent, connection, ...hostFields() };
+  let context = targetContext() ?? process.env.CODEX_THREAD_ID;
+  if (targetHost() !== "local" && remoteTransport() === "native" && !context) throw Object.assign(new Error("Remote supervision requires --context-thread <LOCAL-THREAD-ID> or CODEX_THREAD_ID."), { code: "REMOTE_CONTEXT_REQUIRED" });
+  if (targetHost() !== "local" && remoteTransport() === "native") {
+    const source = parseThreadTarget(context);
+    if (source.hostId !== undefined && source.hostId !== "local") throw Object.assign(new Error("Remote supervision needs a local --context-thread."), { code: "REMOTE_CONTEXT_INVALID" });
+    context = source.threadId;
+  }
+  const sessionOptions = `--supervisor ${shellArgument(supervisor.session_id)} --connection ${connection}${targetHost() === "local" ? "" : ` --host ${shellArgument(targetHost())} --remote-transport ${remoteTransport()}${context ? ` --context-thread ${shellArgument(context)}` : ""}`}`;
+  const { command: baseCommand, ...runtime } = await preparePromptCommand(usePathCli);
+  const command = `${baseCommand} ${sessionOptions}`;
   if (usePathCli) {
-    return { ...pathSupervisorPrompt(threadId, `codexteer ${sessionOptions}`, policy, supervisor, { usePathCli: true }),
-      cli_mode: "path", deployment: null, node: null, supervisor };
+    return { ...pathSupervisorPrompt(threadId, command, policy, supervisor, { usePathCli: true }), ...runtime, supervisor };
   }
-  const node = { path: await realpath(process.execPath), version: process.version };
-  const home = codexHome();
-  shellArgument(node.path); shellArgument(home);
-  const deployment = await prepareDeployment(home);
-  // Bind the validated canonical profile as well as the saved executable.
-  const command = `CODEX_HOME=${shellArgument(deployment.codex_home)} ${shellArgument(node.path)} ${shellArgument(path.join(deployment.directory, "bin/codexteer.mjs"))} --require-node-version ${shellArgument(node.version)} ${sessionOptions}`;
   // Render with the saved distribution's implementation as well as its CLI.
   // An update to the source/cache after placement cannot mix prompt and code.
-  const { supervisorPrompt } = await import(pathToFileURL(path.join(deployment.directory, "src/prompt.mjs")).href);
-  return { ...supervisorPrompt(threadId, command, policy, supervisor), cli_mode: "saved", deployment, node, supervisor };
-}
-
-function launchFailure(agent, error) {
-  return Object.assign(new Error(`Could not start ${agent} (${error.code ?? "START_FAILED"}). Check that it is installed and executable on PATH.`), { code: error.code ?? "START_FAILED" });
+  const { supervisorPrompt } = await import(pathToFileURL(path.join(runtime.deployment.directory, "src/prompt.mjs")).href);
+  return { ...supervisorPrompt(threadId, command, policy, supervisor), ...runtime, supervisor };
 }
 
 export async function superviseAgent(threadInput, { agent = "claude", agentArgs = [], policy, connection = "shared", usePathCli = false } = {}) {
   const { prompt, thread_id: threadId, supervisor, deployment } = await prepareSupervisorPrompt(threadInput, policy, { agent, connection, usePathCli });
   const storage = { home: deployment?.codex_home ?? await prepareCodexHome(codexHome()) };
-  await registerSupervisor(threadId, supervisor.session_id, { ...storage, owner: agent, launcherPid: process.pid, connection });
-  try { return await launchSupervisorAgent(agent, agentArgs, prompt); }
+  await registerSupervisor(threadId, supervisor.session_id, { ...storage, owner: agent, launcherPid: process.pid, connection: supervisor.connection });
+  try { return await launchAgent(agent, agentArgs, prompt); }
   finally {
     try { await controlSupervisor(threadId, "stop", { ...storage, expectedSession: supervisor.session_id }); }
     catch (error) {
@@ -61,23 +53,3 @@ export async function superviseAgent(threadInput, { agent = "claude", agentArgs
     }
   }
 }
-
-async function launchSupervisorAgent(agent, agentArgs, prompt) {
-  let child;
-  try {
-    // Keep forwarded argv intact. The agent's own terminator keeps its variadic
-    // options from consuming the generated prompt as another option value.
-    child = spawn(agent, [...agentArgs, "--", prompt], { shell: false, stdio: "inherit" });
-  } catch (error) { throw launchFailure(agent, error); }
-
-  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
-  const handlers = signals.map(signal => () => {
-    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
-  });
-  signals.forEach((signal, index) => process.on(signal, handlers[index]));
-  try {
-    const [code, signal] = await once(child, "exit");
-    return code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1);
-  } catch (error) { throw launchFailure(agent, error); }
-  finally { signals.forEach((signal, index) => process.off(signal, handlers[index])); }
-}

package/src/supervision.mjs

@@ -1,9 +1,20 @@
+import { isDesktopCloudTask } from "./desktop-cloud-id.mjs";
 import { readRecord, writeRecord, listRecords, withStoreLock } from "./store.mjs";
-import { normalizeThreadId } from "./thread-id.mjs";
+import { targetHost, remoteReadOnly, remoteTransport, isControlTransport } from "./target.mjs";
+import { normalizeTaskId, isCloudTask } from "./task-id.mjs";
 import { isAlive } from "./runtime.mjs";
 
 const failure = (message, code) => Object.assign(new Error(message), { code });
 const states = new Set(["active", "paused", "stopped"]);
+const supervisorBucket = id => (isCloudTask(id) || isDesktopCloudTask(id)) ? "cloud-supervisors" : "supervisors";
+function launcherAlive(record) {
+  if (record.launcher_pid === null) return null;
+  try { return isAlive(record.launcher_pid); }
+  catch (error) {
+    if (error.code === "PERMISSION_DENIED") throw failure("Cannot verify the supervisor launcher process. This execution sandbox may deny process inspection; no liveness was inferred.", "PERMISSION_DENIED");
+    throw error;
+  }
+}
 
 export function supervisorId(value) {
   if (typeof value !== "string" || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(value)) throw failure("Invalid supervisor session ID.", "SUPERVISOR_INVALID");
@@ -11,10 +22,10 @@ export function supervisorId(value) {
 }
 
 export async function getSupervisor(threadInput, storage = {}) {
-  const threadId = normalizeThreadId(threadInput), record = await readRecord("supervisors", threadId, storage);
+  const threadId = normalizeTaskId(threadInput), record = await readRecord(supervisorBucket(threadId), threadId, storage);
   if (!record) return null;
   if (record.schema !== 1 || record.thread_id !== threadId || !states.has(record.state)
-    || !["shared", "desktop"].includes(record.connection)
+    || !["shared", "desktop", "cloud", "desktop-cloud"].includes(record.connection)
     || supervisorId(record.session_id) !== record.session_id || typeof record.owner !== "string"
     || (record.launcher_pid !== null && (!Number.isSafeInteger(record.launcher_pid) || record.launcher_pid <= 0))) {
     throw failure("Invalid supervisor state. Inspect the local record before continuing.", "SUPERVISOR_INVALID");
@@ -27,17 +38,18 @@ export async function assertSupervisor(threadInput, sessionInput, { sending = fa
   if (!record) throw failure("Register this supervisor session before observing or sending.", "SUPERVISOR_NOT_REGISTERED");
   if (record.session_id !== sessionId) throw failure("Another supervisor session owns this task. This command belongs to an older or different session.", "SUPERVISOR_MISMATCH");
   if (connection !== undefined && record.connection !== connection) throw failure("The supervisor is registered for another connection. Keep the original command intact.", "SUPERVISOR_MISMATCH");
+  if (targetHost() !== "local" && (record.remote_transport ?? "native") !== remoteTransport()) throw failure("The supervisor belongs to a different remote transport. Keep the generated route intact.", "SUPERVISOR_MISMATCH");
   if (record.state === "stopped") throw failure("This supervisor session has stopped. Start a new supervisor when needed.", "SUPERVISOR_STOPPED");
-  if (record.launcher_pid !== null && !isAlive(record.launcher_pid)) throw failure("The supervisor launcher exited. Stop the stale session before starting another supervisor.", "SUPERVISOR_ORPHANED");
+  if (launcherAlive(record) === false) throw failure("The supervisor launcher exited. Stop the stale session before starting another supervisor.", "SUPERVISOR_ORPHANED");
   if (sending && record.state === "paused") throw failure("Automatic intervention is paused. Observation can continue; only the user should resume intervention.", "SUPERVISOR_PAUSED");
   return record;
 }
 
 export async function registerSupervisor(threadInput, sessionInput, { owner = "external", launcherPid = null, connection = "shared", ...storage } = {}) {
-  const threadId = normalizeThreadId(threadInput), sessionId = supervisorId(sessionInput);
+  const threadId = normalizeTaskId(threadInput), sessionId = supervisorId(sessionInput);
   if (typeof owner !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(owner)) throw failure("Supervisor owner must be a short agent name.", "SUPERVISOR_INVALID");
   if (launcherPid !== null && (!Number.isSafeInteger(launcherPid) || launcherPid <= 0)) throw failure("Invalid supervisor launcher PID.", "SUPERVISOR_INVALID");
-  if (!["shared", "desktop"].includes(connection)) throw failure("Invalid supervisor connection.", "SUPERVISOR_INVALID");
+  if (!["shared", "desktop", "cloud", "desktop-cloud"].includes(connection)) throw failure("Invalid supervisor connection.", "SUPERVISOR_INVALID");
   return withStoreLock(`supervisor-${threadId}`, async () => {
     const current = await getSupervisor(threadId, storage);
     if (current?.session_id === sessionId) {
@@ -48,44 +60,45 @@ export async function registerSupervisor(threadInput, sessionInput, { owner = "e
     const now = new Date().toISOString();
     const record = { schema: 1, thread_id: threadId, session_id: sessionId, owner, launcher_pid: launcherPid, connection,
       state: "active", registered_at: now, updated_at: now, last_delivery: null };
-    await writeRecord("supervisors", threadId, record, storage);
+    await writeRecord(supervisorBucket(threadId), threadId, record, storage);
     return record;
   }, storage);
 }
 
 export async function controlSupervisor(threadInput, action, { expectedSession, ...storage } = {}) {
-  const threadId = normalizeThreadId(threadInput);
+  const threadId = normalizeTaskId(threadInput);
   if (!["pause", "resume", "stop"].includes(action)) throw failure("Expected pause, resume or stop.", "SUPERVISOR_INVALID");
   return withStoreLock(`supervisor-${threadId}`, async () => {
     const record = await getSupervisor(threadId, storage);
     if (!record) throw failure("No supervisor is registered for this task.", "SUPERVISOR_NOT_REGISTERED");
+    if (targetHost() !== "local" && (record.remote_transport ?? "native") !== remoteTransport()) throw failure("Keep the registered remote transport when controlling this supervisor. No state was changed.", "SUPERVISOR_MISMATCH");
     if (expectedSession && record.session_id !== supervisorId(expectedSession)) throw failure("The supervisor session changed.", "SUPERVISOR_MISMATCH");
     if (record.state === "stopped" && action !== "stop") throw failure("A stopped supervisor cannot be resumed. Start a new supervisor.", "SUPERVISOR_STOPPED");
     if (action === "resume") await assertSupervisor(threadId, record.session_id, storage);
     const updated = { ...record, state: { pause: "paused", resume: "active", stop: "stopped" }[action], updated_at: new Date().toISOString() };
-    await writeRecord("supervisors", threadId, updated, storage);
+    await writeRecord(supervisorBucket(threadId), threadId, updated, storage);
     return updated;
   }, storage);
 }
 
 export async function supervisorStatus(threadInput, storage = {}) {
-  const threadId = normalizeThreadId(threadInput), record = await getSupervisor(threadId, storage);
+  const threadId = normalizeTaskId(threadInput), record = await getSupervisor(threadId, storage);
   if (!record) return { thread_id: threadId, state: "unregistered", observation: null };
   const observation = await readRecord("supervisor-observations", record.session_id, storage);
   if (observation && (observation.schema !== 1 || observation.thread_id !== threadId || observation.session_id !== record.session_id)) throw failure("Invalid supervisor observation record.", "SUPERVISOR_INVALID");
-  return { ...record, launcher_alive: record.launcher_pid === null ? null : isAlive(record.launcher_pid),
+  return { ...record, launcher_alive: launcherAlive(record),
     observation, observation_age_ms: observation?.last_observed_at ? Math.max(0, Date.now() - Date.parse(observation.last_observed_at)) : null };
 }
 
 export async function listSupervisors(storage = {}) {
-  const records = await listRecords("supervisors", storage);
+  const records = (await Promise.all([listRecords("supervisors", storage), listRecords("cloud-supervisors", storage)])).flat();
   return Promise.all(records.filter(Boolean).map(record => supervisorStatus(record.thread_id, storage)));
 }
 
 // Observation has its own record so a concurrent read never overwrites pause/stop.
 // This timestamp records CLI observation, not acknowledgement by the supervising AI.
 export async function recordSupervisorObservation(threadInput, sessionInput, data, storage = {}) {
-  const threadId = normalizeThreadId(threadInput), sessionId = supervisorId(sessionInput);
+  const threadId = normalizeTaskId(threadInput), sessionId = supervisorId(sessionInput);
   await assertSupervisor(threadId, sessionId, storage);
   const key = `supervisor-observe-${sessionId}`;
   try {
@@ -110,25 +123,34 @@ export async function recordSupervisorFailure(threadId, sessionId, error, storag
   catch { /* The original failure is returned to the consumer. */ }
 }
 
-export async function withSupervisedSend(threadInput, sessionInput, send, { connection, ...storage } = {}) {
-  if (sessionInput === undefined) return send();
-  const threadId = normalizeThreadId(threadInput), sessionId = supervisorId(sessionInput);
+export async function withSupervisedMutation(threadInput, sessionInput, mutate, { connection, ...storage } = {}) {
+  if (targetHost() !== "local" && !isControlTransport()) throw remoteReadOnly();
+  if (sessionInput === undefined) return mutate();
+  const threadId = normalizeTaskId(threadInput), sessionId = supervisorId(sessionInput);
   // Holding this lock through the receipt serializes pause/stop with the actual
   // mutation. A busy pause is an error, never a false acknowledgement of a stop.
   return withStoreLock(`supervisor-${threadId}`, async () => {
     const record = await assertSupervisor(threadId, sessionId, { ...storage, sending: true, connection });
+    return mutate(record);
+  }, storage);
+}
+
+export async function withSupervisedSend(threadInput, sessionInput, send, { connection, ...storage } = {}) {
+  return withSupervisedMutation(threadInput, sessionInput, async record => {
+    if (!record) return send();
+    const threadId = record.thread_id;
     try {
       const receipt = await send();
-      try { await writeRecord("supervisors", threadId, { ...record, updated_at: new Date().toISOString(), last_error: null,
+      try { await writeRecord(supervisorBucket(threadId), threadId, { ...record, updated_at: new Date().toISOString(), last_error: null,
         last_delivery: { message_id: receipt.message_id ?? null, status: receipt.delivery_status, at: new Date().toISOString() } }, storage); }
       catch { receipt.supervision_update_required = true; }
       return receipt;
     } catch (error) {
-      try { await writeRecord("supervisors", threadId, { ...record, updated_at: new Date().toISOString(),
+      try { await writeRecord(supervisorBucket(threadId), threadId, { ...record, updated_at: new Date().toISOString(),
         last_error: { code: error.code ?? "SEND_FAILED", existing_message_id: error.existing_message_id ?? null, at: new Date().toISOString() },
         ...(error.message_id ? { last_delivery: { message_id: error.message_id, status: error.delivery_status ?? "not_sent", code: error.code, at: new Date().toISOString() } } : {}) }, storage); }
       catch { error.supervision_update_required = true; }
       throw error;
     }
-  }, storage);
+  }, { connection, ...storage });
 }

package/src/target.mjs

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+
+// One invocation selects one host, including for downstream local records.
+const targets = new AsyncLocalStorage();
+export const targetHost = () => targets.getStore()?.hostId ?? "local";
+export const targetContext = () => targets.getStore()?.contextThread;
+export const remoteTransport = () => targets.getStore()?.remoteTransport ?? "native";
+export const isControlTransport = (transport = remoteTransport()) => ["control", "paired"].includes(transport);
+export function validateRemoteTransport(value) {
+  if (!["native", "control", "paired"].includes(value)) throw Object.assign(new Error("--remote-transport must be native, control or paired."), { code: "INVALID_REMOTE_TRANSPORT" });
+  return value;
+}
+export function validateHostId(hostId) {
+  if (typeof hostId !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9:._-]{0,239}$/.test(hostId)) {
+    throw Object.assign(new Error("Invalid host ID."), { code: "INVALID_HOST" });
+  }
+  return hostId;
+}
+export const withTarget = (hostId, contextThread, operation, { transport = "native" } = {}) => targets.run({ hostId: validateHostId(hostId), contextThread, remoteTransport: validateRemoteTransport(transport) }, operation);
+export const hostNamespace = () => targetHost() === "local" ? null : createHash("sha256").update(targetHost()).digest("hex");
+export const hostFields = () => targetHost() === "local" ? {} : { host_id: targetHost(), remote_transport: remoteTransport() };
+export function remoteReadOnly() {
+  return Object.assign(new Error("The native remote route supports observation only. Select --remote-transport paired for remote task creation, listing and new-turn operations, or a configured control route for active-turn steering. No route was switched automatically."), { code: "REMOTE_READ_ONLY", sent: false, delivery_status: "not_sent" });
+}

package/src/task-id.mjs

@@ -0,0 +1,23 @@
+import { isDesktopCloudTask, desktopCloudId } from "./desktop-cloud-id.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { isCloudTask, cloudTaskId } from "./cloud-id.mjs";
+
+export { isCloudTask } from "./cloud-id.mjs";
+
+// Shared records use the actual backend identifier. Desktop RPC boundaries
+// retain their strict UUID validator, so a cloud ID cannot reach a local task.
+export function normalizeTaskId(value) {
+  return isDesktopCloudTask(value) ? desktopCloudId(value) : isCloudTask(value) ? cloudTaskId(value) : normalizeThreadId(value);
+}
+
+export function taskConnection(value, selected = "shared") {
+  if (isDesktopCloudTask(value)) {
+    if (!["shared", "desktop-cloud"].includes(selected)) throw Object.assign(new Error("Desktop Cloud cannot use another connection."), { code: "CLOUD_TARGET_CONFLICT" });
+    return "desktop-cloud";
+  }
+  if (selected === "desktop-cloud") throw Object.assign(new Error("Use a durable_ ID or hostId=durable link for Desktop Cloud."), { code: "CLOUD_TARGET_CONFLICT" });
+  const cloud = isCloudTask(value);
+  if (cloud && selected === "desktop") throw Object.assign(new Error("A cloud task cannot use a Desktop observation endpoint."), { code: "CLOUD_TARGET_CONFLICT" });
+  if (!cloud && selected === "cloud") throw Object.assign(new Error("The cloud connection requires a cloud task ID or link."), { code: "CLOUD_TARGET_CONFLICT" });
+  return cloud ? "cloud" : selected;
+}

package/src/thread-create.mjs

@@ -10,7 +10,7 @@ import { readSendState } from "./app-server.mjs";
 import { fetchThread } from "./observe.mjs";
 import { discoverNativeEndpoint, inspectNativeEndpoint, nativeToolJson } from "./native-rpc.mjs";
 import { nativeOnAppServer, inspectNativeCommandProtocol, mutationOutcomeUnknown } from "./native-command.mjs";
-import { desktopMembership, initialInstructionMatches } from "./creation-verification.mjs";
+import { desktopMembership, initialInstructionMatches, validateMembershipCatalog } from "./creation-verification.mjs";
 import { writeRecord, storePath } from "./store.mjs";
 import { createStandaloneProjectThread } from "./standalone-create.mjs";
 
@@ -26,11 +26,12 @@ export function creationOptions(options = {}) {
 }
 
 export function validateNativeCreationCatalog(catalog) {
+  const membership = validateMembershipCatalog(catalog);
   const schemas = ["list_projects", "create_thread"].map(name => catalog?.tools?.find(tool => tool.name === name && tool.namespace === "codex_app")?.inputSchema);
   const creation = schemas[1], project = creation?.properties?.target?.anyOf?.find(target => target.properties?.type?.enum?.includes("project"));
   const local = project?.properties?.environment?.anyOf?.find(environment => environment.properties?.type?.enum?.includes("local"));
   if (schemas[0]?.type !== "object" || creation?.properties?.prompt?.type !== "string" || !creation.required?.includes("prompt") || !creation.required.includes("target") || project?.properties?.projectId?.type !== "string" || !project.required?.includes("projectId") || !local) throw failure("Desktop native tools do not expose the required local creation schema.", "NATIVE_CREATION_UNSUPPORTED");
-  return { status: "verified", source: "desktop-native-schema", schema_sha256: createHash("sha256").update(JSON.stringify(schemas)).digest("hex") };
+  return { status: "verified", source: "desktop-native-schema", schema_sha256: createHash("sha256").update(JSON.stringify([...schemas, membership])).digest("hex") };
 }
 
 export async function createProjectThread(selector, prompt, options = {}, dependencies = {}) {
@@ -99,7 +100,7 @@ export async function createProjectThread(selector, prompt, options = {}, depend
     await write("creations", attemptId, receipt, storage);
     if (!accepted) throw failure("Child exists but its initial turn was not confirmed. Inspect the child before resending.", "INITIAL_TURN_UNCONFIRMED");
     const thread = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
-    if (thread?.id !== threadId || thread.cwd !== scope.cwd || !await membership(paths.home, threadId, selected.projectId)) throw failure("Created child did not confirm the selected Desktop project.", "DESKTOP_MEMBERSHIP_MISMATCH");
+    if (thread?.id !== threadId || thread.cwd !== scope.cwd || !await membership(invokeNative, nativeEndpoint, threadId, selected.projectId, context, nativeOptions)) throw failure("Created child did not confirm the selected Desktop project.", "DESKTOP_MEMBERSHIP_MISMATCH");
     const roots = thread.environments?.find(environment => environment.environmentId === "local")?.runtimeWorkspaceRoots;
     if (!Array.isArray(roots) || roots.length !== scope.runtimeWorkspaceRoots.length || !scope.runtimeWorkspaceRoots.every(root => roots.includes(root))) throw failure("Created child did not confirm all project source folders.", "CREATION_SCOPE_MISMATCH");
     let saved = await history(client, threadId), named = thread;

package/src/thread-id.mjs

@@ -1,11 +1,12 @@
+import { targetHost, validateHostId } from "./target.mjs";
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-export function normalizeThreadId(input) {
+export function parseThreadTarget(input) {
   if (typeof input !== "string" || input.trim() === "") {
     throw new Error("Thread ID is required.");
   }
 
-  let value = input.trim();
+  let value = input.trim(), hostId;
   if (value.startsWith("codex://")) {
     let url;
     try {
@@ -16,20 +17,34 @@ export function normalizeThreadId(input) {
     if (url.hostname !== "threads") {
       throw new Error(`Expected codex://threads/<thread-id>: ${input}`);
     }
+    const hosts = url.searchParams.getAll("hostId");
+    if (hosts.length > 1) throw new Error("A thread link must have only one hostId.");
+    if (hosts.length) hostId = validateHostId(hosts[0]);
     value = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
   }
 
   if (!UUID_PATTERN.test(value)) {
     throw new Error(`Invalid local Codex thread ID: ${input}`);
   }
-  return value.toLowerCase();
+  return { threadId: value.toLowerCase(), hostId };
+}
+
+export function normalizeThreadId(input) {
+  const { threadId, hostId } = parseThreadTarget(input);
+  if (hostId !== undefined && hostId !== targetHost()) {
+    throw Object.assign(new Error("Thread link belongs to another host. Select its host with --host or the host-aware CLI entry point."), { code: "HOST_MISMATCH" });
+  }
+  return threadId;
 }
 
 export function threadDeepLink(threadId) {
-  return `codex://threads/${normalizeThreadId(threadId)}`;
+  const target = parseThreadTarget(threadId), host = target.hostId ?? targetHost();
+  const link = `codex://threads/${target.threadId}`;
+  return host === "local" ? link : `${link}?${new URLSearchParams({ hostId: host })}`;
 }
 
 export function threadComposerDeepLink(threadId, prompt = "") {
-  const query = new URLSearchParams({ prompt });
-  return `${threadDeepLink(threadId)}?${query}`;
+  const link = new URL(threadDeepLink(threadId));
+  link.searchParams.set("prompt", prompt);
+  return link.toString();
 }

package/src/thread-verify.mjs

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { discoverRuntime } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+import { assertRuntimeOperation, compatibleClient } from "./compatibility.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { projectAliases, projectWorkspace, validateProject } from "./projects.mjs";
+import { fetchThread } from "./observe.mjs";
+import { discoverNativeEndpoint, inspectNativeEndpoint } from "./native-rpc.mjs";
+import { nativeOnAppServer, inspectNativeCommandProtocol } from "./native-command.mjs";
+import { desktopMembership, initialInstructionText, validateMembershipCatalog } from "./creation-verification.mjs";
+import { readRecord, writeRecord, storePath, withStoreLock } from "./store.mjs";
+
+const failure = (message, code = "CREATION_VERIFICATION_FAILED") => Object.assign(new Error(message), { code });
+const sameRoots = (actual, expected) => Array.isArray(actual) && actual.length === expected.length && expected.every(root => actual.includes(root));
+const text = value => typeof value === "string" && !!value.trim();
+
+function validateReceipt(receipt, attemptId) {
+  if (!receipt || receipt.attempt_id !== attemptId || receipt.dry_run
+    || !((receipt.schema === 3 && receipt.creation_mode === "standalone") || (receipt.schema === 2 && receipt.creation_mode === "delegated"))
+    || receipt.creation_status !== "created" || receipt.sent !== true || receipt.delivery_status !== "accepted"
+    || !text(receipt.thread_id) || normalizeThreadId(receipt.thread_id) !== receipt.thread_id
+    || !text(receipt.project_id) || !text(receipt.desktop_project_id) || !text(receipt.cwd) || !path.isAbsolute(receipt.cwd)
+    || !Array.isArray(receipt.runtime_workspace_roots) || !receipt.runtime_workspace_roots.length
+    || receipt.runtime_workspace_roots.some(root => !text(root) || !path.isAbsolute(root))
+    || new Set(receipt.runtime_workspace_roots).size !== receipt.runtime_workspace_roots.length
+    || !/^[a-f0-9]{64}$/.test(receipt.prompt_sha256 ?? "") || !Number.isSafeInteger(receipt.message_characters) || receipt.message_characters < 1
+    || (receipt.creation_mode === "standalone" ? !text(receipt.turn_id) || !text(receipt.title) : !text(receipt.context_thread_id))) {
+    throw failure("A valid created/accepted receipt is required. Inspect the existing task; this command never creates or resends.", "CREATION_RECEIPT_UNVERIFIED");
+  }
+}
+
+// Recovery of a known created/accepted attempt. Only the codexteer receipt is
+// written. No create, subscribe, move, metadata update, start or steer API is
+// available in this operation; native access is restricted to two read tools.
+export async function verifyProjectThread(attempt, { timeoutMs = 120000 } = {}, {
+  discover = discoverRuntime, connect = RpcClient.connect, aliases = projectAliases,
+  endpoint = discoverNativeEndpoint, inspectEndpoint = inspectNativeEndpoint, inspectCommand = inspectNativeCommandProtocol, native,
+  workspace = projectWorkspace, history = fetchThread, membership = desktopMembership,
+  read = readRecord, write = writeRecord, lock = withStoreLock,
+} = {}) {
+  const attemptId = normalizeThreadId(attempt);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000) throw failure("--timeout-ms must be 1000..600000.", "INVALID_CREATION_OPTIONS");
+  const { paths, state } = await discover(), storage = { home: paths.home };
+  assertRuntimeOperation(state, "read");
+  return lock(`creation-${attemptId}`, async () => {
+    const receipt = await read("creations", attemptId, storage);
+    validateReceipt(receipt, attemptId);
+    let client;
+    try {
+      const nativeEndpoint = await endpoint(state);
+      await inspectCommand(state);
+      client = compatibleClient(await connect(paths.socket, { timeoutMs: timeoutMs + 5000 }), state);
+      const invoke = native ?? ((...args) => nativeOnAppServer(client, ...args));
+      const readNative = (...args) => {
+        if (!["catalog", "list_threads"].includes(args[1])) throw failure("Verification permits only native reads.");
+        return invoke(...args);
+      };
+      validateMembershipCatalog(await readNative(nativeEndpoint, "catalog", undefined, undefined, { timeoutMs }));
+      const project = validateProject((await client.request("project/read", { projectId: receipt.project_id })).project);
+      const scope = await workspace(project, receipt.cwd);
+      const thread = (await client.request("thread/read", { threadId: receipt.thread_id, includeTurns: false })).thread;
+      const saved = await history(client, receipt.thread_id), first = saved.turns?.[0];
+      const instruction = initialInstructionText(saved, receipt.creation_mode === "delegated" ? receipt.context_thread_id : undefined);
+      const roots = thread?.environments?.find(environment => environment.environmentId === "local")?.runtimeWorkspaceRoots;
+      const checks = {
+        thread_id: thread?.id === receipt.thread_id,
+        project_mapping: (await aliases(paths.home))[receipt.desktop_project_id] === receipt.project_id,
+        project_roots: project.id === receipt.project_id && sameRoots(scope.runtimeWorkspaceRoots, receipt.runtime_workspace_roots),
+        canonical_project_id: thread?.projectId === receipt.project_id,
+        cwd: thread?.cwd === receipt.cwd && scope.cwd === receipt.cwd,
+        roots: sameRoots(roots, receipt.runtime_workspace_roots),
+        title: receipt.title == null || thread?.name === receipt.title,
+        initial_turn: text(first?.id) && (receipt.creation_mode !== "standalone" || first.id === receipt.turn_id),
+        initial_instruction: typeof instruction === "string" && [...instruction].length === receipt.message_characters
+          && createHash("sha256").update(instruction).digest("hex") === receipt.prompt_sha256,
+        desktop_membership: text(first?.id) && await membership(readNative, nativeEndpoint, receipt.thread_id, receipt.desktop_project_id,
+          { threadId: receipt.thread_id, turnId: first.id }, { timeoutMs }),
+      };
+      const current = await discover(); assertRuntimeOperation(current.state, "read");
+      if (current.state.instance !== state.instance || current.paths.socket !== paths.socket || current.paths.home !== paths.home || current.state.cli_version !== state.cli_version) {
+        throw failure("Runtime changed during verification. No task was changed.", "RUNTIME_CHANGED");
+      }
+      await inspectEndpoint(nativeEndpoint.socketPath, nativeEndpoint.fingerprint);
+      const verified = Object.values(checks).every(value => value === true), status = verified ? "verified" : "failed";
+      const updated = { ...receipt, receipt_path: storePath("creations", attemptId, paths.home), verification_status: status,
+        verification_history: [...(receipt.verification_history ?? []), { checked_at: new Date().toISOString(), status, checks,
+          source: "desktop-native-list_threads", desktop_reads_only: true,
+          previous_status: receipt.verification_status, ...(receipt.error_code ? { previous_error_code: receipt.error_code } : {}) }] };
+      if (verified) {
+        Object.assign(updated, { desktop_project_membership: "verified", app_server_project_membership: "verified", initial_instruction: "verified" });
+        delete updated.error_code;
+      } else {
+        updated.error_code = "CREATION_VERIFICATION_FAILED";
+        // Never leave earlier certification flags on a failed fresh check.
+        delete updated.desktop_project_membership; delete updated.app_server_project_membership; delete updated.initial_instruction;
+      }
+      try { await write("creations", attemptId, updated, storage); }
+      catch { throw Object.assign(failure("Verification finished but its receipt could not be saved. Do not recreate or resend.", "CREATION_RECEIPT_UPDATE_FAILED"), { receipt_update_required: true, verification_checks: checks }); }
+      if (!verified) throw Object.assign(failure("Existing task did not pass all creation checks. No task was changed; do not recreate or resend."), { verification_checks: checks });
+      return updated;
+    } catch (error) {
+      Object.assign(error, { attempt_id: attemptId, thread_id: receipt.thread_id, creation_status: receipt.creation_status,
+        sent: receipt.sent, delivery_status: receipt.delivery_status, receipt_path: storePath("creations", attemptId, paths.home) });
+      throw error;
+    } finally { client?.close(); }
+  }, storage);
+}