codexteer 0.16.0 → 0.18.0

package/src/standalone-create.mjs

@@ -0,0 +1,135 @@
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { discoverRuntime, verifyControlEndpoint } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+import { assertRuntimeOperation, compatibleClient } from "./compatibility.mjs";
+import { normalizeThreadId, threadDeepLink } from "./thread-id.mjs";
+import { projectsOnClient, projectAliases, resolveProject, projectWorkspace, validateProject } from "./projects.mjs";
+import { fetchThread } from "./observe.mjs";
+import { ensureDesktopSubscription } from "./subscription.mjs";
+import { discoverNativeEndpoint, inspectNativeEndpoint, nativeToolJson } from "./native-rpc.mjs";
+import { nativeOnAppServer, inspectNativeCommandProtocol, mutationOutcomeUnknown } from "./native-command.mjs";
+import { desktopMembership, initialInstructionMatches, validateMembershipCatalog } from "./creation-verification.mjs";
+import { writeRecord, storePath } from "./store.mjs";
+
+const failure = (message, code = "CREATION_FAILED") => Object.assign(new Error(message), { code });
+
+export function validateStandaloneCreationCatalog(catalog) {
+  const membership = validateMembershipCatalog(catalog);
+  const schema = catalog?.tools?.find(tool => tool.name === "move_thread_to_project" && tool.namespace === "codex_app")?.inputSchema;
+  const list = catalog?.tools?.find(tool => tool.name === "list_projects" && tool.namespace === "codex_app")?.inputSchema;
+  const project = schema?.properties?.projectId;
+  if (list?.type !== "object" || schema?.properties?.threadId?.type !== "string"
+    || !schema.required?.includes("threadId") || !schema.required.includes("projectId")
+    || !(project?.type === "string" || project?.anyOf?.some(type => type.type === "string"))) {
+    throw failure("Desktop native tools do not expose local project assignment.", "NATIVE_CREATION_UNSUPPORTED");
+  }
+  return { status: "verified", source: "desktop-native-assignment-schema", schema_sha256: createHash("sha256").update(JSON.stringify([list, schema, membership])).digest("hex") };
+}
+
+// No caller chat is required. The initial instruction starts exactly one real
+// task/turn; only that new task supplies the native self-assignment context.
+export async function createStandaloneProjectThread(selector, prompt, settings, {
+  discover = discoverRuntime, connect = RpcClient.connect, aliases = projectAliases,
+  endpoint = discoverNativeEndpoint, inspectEndpoint = inspectNativeEndpoint, inspectCommand = inspectNativeCommandProtocol, native,
+  workspace = projectWorkspace, history = fetchThread, membership = desktopMembership,
+  inspectControl = verifyControlEndpoint, subscribe = ensureDesktopSubscription, write = writeRecord, sleep = delay,
+} = {}) {
+  const attemptId = randomUUID();
+  const title = settings.title ?? [...prompt.trim().replace(/\s+/gu, " ")].slice(0, 80).join("");
+  let client, receipt, storage, creating = false, sending = false, accepted = false;
+  try {
+    const { paths, state } = await discover(); storage = { home: paths.home };
+    assertRuntimeOperation(state, "send_new_turn");
+    await inspectControl(paths);
+    const nativeEndpoint = await endpoint(state), command = await inspectCommand(state, { standalone: true });
+    client = compatibleClient(await connect(paths.socket, { timeoutMs: settings.timeoutMs + 5000 }), state);
+    const invokeNative = native ?? ((...args) => nativeOnAppServer(client, ...args));
+    const nativeOptions = { timeoutMs: settings.timeoutMs };
+    const protocol = { ...validateStandaloneCreationCatalog(await invokeNative(nativeEndpoint, "catalog", undefined, undefined, nativeOptions)), command };
+    const mapping = await aliases(paths.home), project = resolveProject(await projectsOnClient(client), selector, mapping), scope = await workspace(project);
+    const matches = Object.keys(mapping).filter(id => mapping[id] === project.id);
+    const desktopId = mapping[selector] === project.id ? selector : matches.length === 1 ? matches[0] : undefined;
+    if (!desktopId) throw failure("Cannot uniquely map this local project to Desktop. No chat was created.", "DESKTOP_PROJECT_MAPPING_UNVERIFIED");
+    const check = async () => {
+      const current = await discover(); assertRuntimeOperation(current.state, "send_new_turn");
+      if (current.state.instance !== state.instance || current.paths.socket !== paths.socket || current.paths.control !== paths.control || current.state.cli_version !== state.cli_version) throw failure("Runtime changed. Inspect the receipt before retrying.", "RUNTIME_CHANGED");
+      await inspectControl(current.paths); await inspectEndpoint(nativeEndpoint.socketPath, nativeEndpoint.fingerprint);
+      const live = validateProject((await client.request("project/read", { projectId: project.id })).project);
+      if (!isDeepStrictEqual(live.roots, project.roots) || live.name !== project.name || (await aliases(paths.home))[desktopId] !== project.id) throw failure("Project source folders or Desktop mapping changed.", "PROJECT_CHANGED");
+    };
+    await check();
+    receipt = { schema: 3, attempt_id: attemptId, native_call_id: attemptId, creation_mode: "standalone", project_id: project.id, desktop_project_id: desktopId, project_name: project.name,
+      context_thread_id: null, context_turn_id: null, cwd: scope.cwd, runtime_workspace_roots: scope.runtimeWorkspaceRoots,
+      title, title_source: settings.title === undefined ? "initial-instruction" : "explicit", backend: "app-server-native-assignment", connection_mode: "shared", protocol,
+      creation_status: "not_created", sent: false, delivery_status: "not_sent", verification_status: "not_started",
+      message_characters: [...prompt].length, prompt_sha256: createHash("sha256").update(prompt).digest("hex"), dry_run: !!settings.dryRun };
+    if (settings.dryRun) return receipt;
+    receipt.receipt_path = storePath("creations", attemptId, paths.home);
+    await write("creations", attemptId, { ...receipt, creation_status: "dispatching" }, storage);
+    await check(); creating = true;
+    const started = await client.request("thread/start", { cwd: scope.cwd, projectId: project.id, runtimeWorkspaceRoots: scope.runtimeWorkspaceRoots,
+      ephemeral: false, ...(settings.model === undefined ? {} : { model: settings.model }) }, { mutation: true });
+    if (!started?.thread?.id) throw Object.assign(failure("No created task ID was confirmed. Do not retry automatically.", "NATIVE_CREATION_UNKNOWN"), { uncertain: true });
+    const threadId = normalizeThreadId(started.thread.id);
+    Object.assign(receipt, { thread_id: threadId, deep_link: threadDeepLink(threadId), creation_status: "created" });
+    await write("creations", attemptId, receipt, storage);
+    await check();
+    // Naming also materializes the turnless rollout on supported servers;
+    // without it both metadata/update and Desktop's resume can fail.
+    await client.request("thread/name/set", { threadId, name: title }, { mutation: true });
+    // An untouched, turnless thread can have no durable rollout yet. Persist
+    // its canonical assignment through the API before Desktop resumes it.
+    await client.request("thread/metadata/update", { threadId, projectId: project.id }, { mutation: true });
+    // Subscribe on Desktop's long-lived connection before starting any work.
+    await subscribe(paths.control, threadId); receipt.desktop_subscription = "verified";
+    await check();
+    const prepared = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
+    const preparedRoots = prepared?.environments?.find(environment => environment.environmentId === "local")?.runtimeWorkspaceRoots;
+    if (prepared?.id !== threadId || prepared.projectId !== project.id || prepared.cwd !== scope.cwd
+      || !Array.isArray(preparedRoots) || preparedRoots.length !== scope.runtimeWorkspaceRoots.length || !scope.runtimeWorkspaceRoots.every(root => preparedRoots.includes(root))
+      || prepared.canAcceptDirectInput === false || (await history(client, threadId)).turns?.length !== 0) {
+      throw failure("New task's scope or empty initial history changed before delivery. No instruction was sent.", "CREATION_SCOPE_MISMATCH");
+    }
+    receipt.client_message_id = randomUUID();
+    await write("creations", attemptId, { ...receipt, delivery_status: "dispatching" }, storage);
+    sending = true;
+    const delivery = await client.request("turn/start", { threadId, input: [{ type: "text", text: prompt }], clientUserMessageId: receipt.client_message_id,
+      ...(settings.thinking === undefined ? {} : { effort: settings.thinking }) }, { mutation: true });
+    if (typeof delivery?.turn?.id !== "string" || !delivery.turn.id.trim()) throw Object.assign(failure("No initial turn ID was confirmed. Inspect the task before resending.", "INITIAL_TURN_UNCONFIRMED"), { uncertain: true });
+    accepted = true;
+    Object.assign(receipt, { turn_id: delivery.turn.id, sent: true, delivery_status: "accepted", native_context_thread_id: threadId, native_context_turn_id: delivery.turn.id });
+    await write("creations", attemptId, receipt, storage);
+    const context = { threadId, turnId: delivery.turn.id };
+    const inventory = nativeToolJson(await invokeNative(nativeEndpoint, "list_projects", {}, context, nativeOptions));
+    const selected = inventory.projects?.filter(item => item.projectKind === "local" && item.hostId === "local" && item.projectId === desktopId);
+    if (selected?.length !== 1 || selected[0].label !== project.name || selected[0].path !== project.roots[0].path) throw failure("Desktop project mapping was not confirmed. Inspect the created task.", "DESKTOP_PROJECT_MAPPING_UNVERIFIED");
+    await check();
+    const assigned = await invokeNative(nativeEndpoint, "move_thread_to_project", { threadId, projectId: desktopId }, context, { ...nativeOptions, callId: attemptId });
+    nativeToolJson(assigned);
+    if (assigned.native_request_cleanup_required) receipt.native_request_cleanup_required = true;
+    const verify = async () => {
+      const thread = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
+      const roots = thread?.environments?.find(environment => environment.environmentId === "local")?.runtimeWorkspaceRoots;
+      return thread?.id === threadId && thread.projectId === project.id && thread.cwd === scope.cwd
+        && Array.isArray(roots) && roots.length === scope.runtimeWorkspaceRoots.length && scope.runtimeWorkspaceRoots.every(root => roots.includes(root))
+        && thread.name === title
+        && await membership(invokeNative, nativeEndpoint, threadId, desktopId, context, nativeOptions) && initialInstructionMatches(await history(client, threadId), prompt);
+    };
+    let verified = await verify();
+    for (let retry = 0; retry < 20 && !verified; retry++) { await sleep(250); verified = await verify(); }
+    if (!verified) throw failure("Created task's assignment, roots, title or initial instruction could not be verified. Do not recreate it.", "CREATION_VERIFICATION_FAILED");
+    Object.assign(receipt, { verification_status: "verified", desktop_project_membership: "verified", app_server_project_membership: "verified", initial_instruction: "verified" });
+    try { await write("creations", attemptId, receipt, storage); } catch { receipt.receipt_update_required = true; }
+    return receipt;
+  } catch (error) {
+    const created = !!receipt?.thread_id, unknownCreation = creating && !created && mutationOutcomeUnknown(error);
+    const unknownDelivery = sending && !accepted && mutationOutcomeUnknown(error);
+    Object.assign(error, { attempt_id: attemptId, native_call_id: attemptId, thread_id: receipt?.thread_id, receipt_path: receipt?.receipt_path,
+      creation_status: created ? "created" : unknownCreation ? "unknown" : "not_created", sent: accepted ? true : unknownDelivery ? null : false,
+      delivery_status: accepted ? "accepted" : unknownDelivery ? "unknown" : "not_sent" });
+    if (receipt?.receipt_path) try { await write("creations", attemptId, { ...receipt, creation_status: error.creation_status, sent: error.sent, delivery_status: error.delivery_status, verification_status: "failed", error_code: error.code ?? "CREATION_FAILED" }, storage); } catch { error.receipt_update_required = true; }
+    throw error;
+  } finally { try { client?.close(); } catch { if (accepted && receipt) receipt.runtime_cleanup_required = true; } }
+}

package/src/store.mjs

@@ -2,12 +2,14 @@ import { lstat, mkdir, readFile, writeFile, rename, rm, readdir, link } from "no
 import { 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 }); }
 }
 

package/src/supervise.mjs

@@ -1,53 +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 { 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 { validateSupervisionPolicy } from "./prompt.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"];
+export { SUPERVISOR_AGENTS };
 
-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 async function prepareSupervisorPrompt(threadInput, policy, { agent = "claude", connection = "shared" } = {}) {
-  const threadId = normalizeThreadId(threadInput);
+export async function prepareSupervisorPrompt(threadInput, policy, { agent = "claude", connection = "shared", usePathCli = false } = {}) {
+  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 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 supervisor = { session_id: randomUUID(), owner: agent, connection };
-  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)} --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, command, policy, supervisor, { usePathCli: true }), ...runtime, supervisor };
+  }
   // 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), deployment, node, supervisor };
+  const { supervisorPrompt } = await import(pathToFileURL(path.join(runtime.deployment.directory, "src/prompt.mjs")).href);
+  return { ...supervisorPrompt(threadId, command, policy, supervisor), ...runtime, 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" });
-}
-
-export async function superviseAgent(threadInput, { agent = "claude", agentArgs = [], policy, connection = "shared" } = {}) {
-  const { prompt, thread_id: threadId, supervisor, deployment } = await prepareSupervisorPrompt(threadInput, policy, { agent, connection });
-  const storage = { home: deployment.codex_home };
-  await registerSupervisor(threadId, supervisor.session_id, { ...storage, owner: agent, launcherPid: process.pid, connection });
-  try { return await launchSupervisorAgent(agent, agentArgs, prompt); }
+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: supervisor.connection });
+  try { return await launchAgent(agent, agentArgs, prompt); }
   finally {
     try { await controlSupervisor(threadId, "stop", { ...storage, expectedSession: supervisor.session_id }); }
     catch (error) {
@@ -56,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;
+}