codexteer 0.16.0 → 0.18.0

package/src/remote-management.mjs

@@ -0,0 +1,234 @@
+import path from "node:path";
+import { randomUUID, createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { discoverRuntime } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+import { readSendState } from "./app-server.mjs";
+import { remoteControlConnection } from "./remote-control.mjs";
+import { targetHost, targetContext, remoteTransport, hostFields } from "./target.mjs";
+import { parseThreadTarget, normalizeThreadId, threadDeepLink } from "./thread-id.mjs";
+import { registeredRemoteProjects } from "./projects.mjs";
+import { discoverNativeEndpoint, nativeToolJson, inspectNativeEndpoint } from "./native-rpc.mjs";
+import { nativeOnAppServer, inspectNativeCommandProtocol } from "./native-command.mjs";
+import { validateNativeCreationCatalog, creationOptions } from "./thread-create.mjs";
+import { fetchThread } from "./observe.mjs";
+import { initialInstructionText } from "./creation-verification.mjs";
+import { writeRecord, readRecord, storePath, withStoreLock } from "./store.mjs";
+
+const failure = (message, code = "REMOTE_MANAGEMENT_FAILED") => Object.assign(new Error(message), { code, uncertain: false });
+const remotePath = value => typeof value === "string" && (path.win32.isAbsolute(value) || path.posix.isAbsolute(value)) && !/[\0\r\n]/.test(value);
+const windowsPath = value => typeof value === "string" && (/^[a-z]:[\\/]/i.test(value) || /^\\\\[^\\]+\\[^\\]+/.test(value));
+const samePath = (a, b) => typeof a === "string" && typeof b === "string" && (a === b || (windowsPath(a) && windowsPath(b) && path.win32.normalize(a).toLowerCase() === path.win32.normalize(b).toLowerCase()));
+export function requirePairedManagement() {
+  if (targetHost() === "local" || remoteTransport() !== "paired") throw failure("Remote management requires an explicit remote host and --remote-transport paired.", "REMOTE_MANAGEMENT_TRANSPORT_REQUIRED");
+}
+
+export async function withRemoteClient(operation, { route = remoteControlConnection, timeoutMs = 35000 } = {}) {
+  requirePairedManagement();
+  const adapter = route(), runtime = await adapter.discover(), client = await adapter.connect(runtime.paths.socket, { timeoutMs });
+  try { return await operation(client, runtime); } finally { client.close(); }
+}
+
+export async function remoteProjectsOnClient(client) {
+  const projects = [], ids = new Set(), cursors = new Set(); let cursor;
+  for (let page = 0; page < 100; page++) {
+    const result = await client.request("project/list", { limit: 100, ...(cursor ? { cursor } : {}) });
+    if (!Array.isArray(result?.data)) throw failure("Invalid remote project list.", "REMOTE_PROTOCOL_ERROR");
+    for (const project of result.data) {
+      if (typeof project?.id !== "string" || !project.id || ids.has(project.id) || typeof project.name !== "string" || !Array.isArray(project.roots) || !project.roots.length || project.roots.some(root => !remotePath(root?.path))) throw failure("Invalid remote project identity or roots.", "REMOTE_PROTOCOL_ERROR");
+      ids.add(project.id); projects.push(project);
+    }
+    if (result.nextCursor == null) return projects;
+    if (typeof result.nextCursor !== "string" || !result.nextCursor || result.nextCursor.length > 16384 || cursors.has(result.nextCursor)) throw failure("Invalid remote project pagination.", "REMOTE_PROTOCOL_ERROR");
+    cursors.add(result.nextCursor); cursor = result.nextCursor;
+  }
+  throw failure("Remote project list exceeded its limit.", "REMOTE_PROTOCOL_ERROR");
+}
+
+export async function listRemoteProjects(dependencies) {
+  return withRemoteClient(async client => {
+    const live = await remoteProjectsOnClient(client), saved = await registeredRemoteProjects();
+    return live.map(project => ({ project_id: project.id, name: project.name, roots: project.roots.map(root => root.path),
+      desktop_project_ids: saved.filter(p => p.host_id === targetHost() && p.roots.length === project.roots.length && p.roots.every(root => project.roots.some(r => samePath(root, r.path)))).map(p => p.project_id),
+      project_kind: "remote", ...hostFields(), source: "remote-app-server", availability: "verified", availability_scope: "project-catalog", roots_availability: "unverified" }));
+  }, dependencies);
+}
+
+export async function listRemoteThreads({ limit = 20, desktopOnly = false, cursor, projectId, search } = {}, dependencies) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500 || (cursor !== undefined && (typeof cursor !== "string" || !cursor || cursor.length > 16384))) throw failure("Invalid remote list limit or cursor.", "INVALID_ARGUMENT");
+  return withRemoteClient(async client => {
+    const threads = [], cursors = new Set(), ids = new Set(); let next = cursor;
+    for (let page = 0; page < 100; page++) {
+      const result = await client.request("thread/list", { limit: Math.min(100, limit - threads.length), useStateDbOnly: true, sortKey: "updated_at",
+        ...(next ? { cursor: next } : {}), ...(projectId ? { projectId } : {}), ...(search ? { searchTerm: search } : {}) });
+      if (!Array.isArray(result?.data) || result.data.length > Math.min(100, limit - threads.length)) throw failure("Invalid remote task list.", "REMOTE_PROTOCOL_ERROR");
+      for (const thread of result.data) {
+        const id = normalizeThreadId(thread?.id);
+        if (ids.has(id)) throw failure("Repeated remote task identity.", "REMOTE_PROTOCOL_ERROR");
+        ids.add(id);
+        if (desktopOnly && thread.originator !== "Codex Desktop") continue;
+        threads.push({ thread_id: id, title: thread.name ?? null, cwd: thread.cwd ?? null, project_id: thread.projectId ?? null,
+          created_at: typeof thread.createdAt === "number" ? new Date(thread.createdAt * 1000).toISOString() : null,
+          updated_at: typeof thread.updatedAt === "number" ? new Date(thread.updatedAt * 1000).toISOString() : null,
+          originator: thread.originator ?? null, deep_link: threadDeepLink(id), ...hostFields() });
+      }
+      next = result.nextCursor;
+      if (next != null && (typeof next !== "string" || !next || next.length > 16384 || cursors.has(next))) throw failure("Invalid remote task pagination.", "REMOTE_PROTOCOL_ERROR");
+      if (next == null || threads.length >= limit) return { threads, count: threads.length, next_cursor: next ?? null, has_more: next != null };
+      cursors.add(next);
+    }
+    throw failure("Remote task pagination exceeded its limit.", "REMOTE_PROTOCOL_ERROR");
+  }, dependencies);
+}
+
+// Desktop owns creation and long-lived subscriptions. The caller is an actual
+// persisted local chat, never a fabricated turn, model relay or a remote task
+// reinterpreted as local. Terminal users may pass --context-thread explicitly.
+export async function remoteDesktopSession({ contextThread = targetContext() ?? process.env.CODEX_THREAD_ID, timeoutMs = 120000 } = {}, dependencies = {}) {
+  const { discover = discoverRuntime, connect = RpcClient.connect, endpoint = discoverNativeEndpoint, inspect = inspectNativeCommandProtocol, native = nativeOnAppServer } = dependencies;
+  if (!contextThread) throw failure("Desktop lifecycle operations require --context-thread <LOCAL-CHAT-ID>, or CODEX_THREAD_ID inside Codex. Paired list/read/steer do not require it.", "REMOTE_CONTEXT_REQUIRED");
+  const source = parseThreadTarget(contextThread);
+  if (source.hostId && source.hostId !== "local") throw failure("The Desktop caller must be a real local chat.", "REMOTE_CONTEXT_INVALID");
+  const runtime = await discover(), client = await connect(runtime.paths.socket, { timeoutMs: timeoutMs + 5000 });
+  try {
+    const pipe = await endpoint(runtime.state); await inspect(runtime.state);
+    const caller = await readSendState(client, source.threadId), turn = caller.turns.at(-1);
+    if (caller.id !== source.threadId || caller.ephemeral || !turn?.id || caller.environments?.some(item => item.environmentId !== "local")) throw failure("A persisted local caller with a stored turn is required.", "REMOTE_CONTEXT_INVALID");
+    const context = { threadId: caller.id, turnId: turn.id };
+    const check = async () => {
+      const current = await discover();
+      if (current.paths.socket !== runtime.paths.socket || current.state.instance !== runtime.state.instance) throw failure("Desktop runtime changed.", "RUNTIME_CHANGED");
+      await inspectNativeEndpoint(pipe.socketPath, pipe.fingerprint);
+    };
+    const catalog = await native(client, pipe, "catalog", undefined, undefined, { timeoutMs });
+    return { context, catalog, close: () => client.close(), async invoke(action, args, options = {}) {
+      if (!["create_thread", "list_threads", "read_thread", "navigate_to_codex_page"].includes(action)) throw failure("Unsupported Desktop management operation.");
+      await check();
+      return nativeToolJson(await native(client, pipe, action, args, context, { timeoutMs, ...options }));
+    } };
+  } catch (error) { client.close(); throw error; }
+}
+
+export async function ensureRemoteDesktopSubscription(threadId, { session: existing, ...options } = {}) {
+  requirePairedManagement();
+  const session = existing ?? await remoteDesktopSession(options);
+  try {
+    const schema = session.catalog.tools?.find(t => t.namespace === "codex_app" && t.name === "navigate_to_codex_page")?.inputSchema;
+    if (schema?.properties?.threadId?.type !== "string") throw failure("Desktop navigation schema is unavailable.", "REMOTE_SUBSCRIPTION_UNVERIFIED");
+    const inventory = await session.invoke("list_threads", {});
+    const matches = [...(inventory.threads ?? []), ...(inventory.pinnedThreads ?? [])].filter(thread => thread.id === threadId);
+    if (matches.length !== 1 || matches[0].hostId !== targetHost()) throw failure("Desktop navigation cannot uniquely identify this task on the selected host. No task was opened.", "HOST_MISMATCH");
+    const snapshot = await session.invoke("read_thread", { threadId, hostId: targetHost(), turnLimit: 1, includeOutputs: false, maxOutputCharsPerItem: 100 });
+    if (snapshot.thread?.id !== threadId || snapshot.thread.hostId !== targetHost()) throw failure("Desktop returned a different task or host.", "HOST_MISMATCH");
+    // Explicitly opens the selected remote chat on the controlling Desktop;
+    // its own persistent App Server connection then resumes/subscribes to it.
+    await session.invoke("navigate_to_codex_page", { threadId });
+    return { thread_id: threadId, ...hostFields(), desktop_subscription: "native-navigation", deep_link: threadDeepLink(threadId) };
+  } finally { if (!existing) session.close(); }
+}
+
+function scopeMatches(thread, receipt) {
+  const roots = thread?.environments?.find(item => item.environmentId === "local")?.runtimeWorkspaceRoots;
+  const match = typeof thread?.path === "string" && thread.path.match(/^(.*)[\\/]sessions[\\/](\d{4})[\\/](\d{2})[\\/](\d{2})[\\/]/);
+  const artifactRoot = match ? windowsPath(thread.path) ? path.win32.join(match[1], "visualizations", match[2], match[3], match[4], receipt.thread_id)
+    : path.posix.join(match[1], "visualizations", match[2], match[3], match[4], receipt.thread_id) : null;
+  return thread?.id === receipt.thread_id && thread.projectId === receipt.project_id && samePath(thread.cwd, receipt.cwd)
+    && thread.name === receipt.title && Array.isArray(roots) && new Set(roots).size === roots.length
+    && receipt.runtime_workspace_roots.every(root => roots.some(actual => samePath(actual, root)))
+    && roots.every(root => receipt.runtime_workspace_roots.some(expected => samePath(root, expected)) || (artifactRoot && samePath(root, artifactRoot)));
+}
+
+export async function createRemoteProjectThread(selector, prompt, options = {}, dependencies = {}) {
+  requirePairedManagement(); const settings = creationOptions(options), attemptId = randomUUID();
+  if (typeof selector !== "string" || !selector.trim() || typeof prompt !== "string" || !prompt.trim()) throw failure("A project and initial instruction are required.", "INVALID_CREATION_OPTIONS");
+  let session, receipt, storage, dispatched = false, accepted = false;
+  const registry = dependencies.registry ?? registeredRemoteProjects;
+  try {
+    session = await (dependencies.desktop ?? remoteDesktopSession)({ contextThread: options.contextThread, timeoutMs: settings.timeoutMs });
+    validateNativeCreationCatalog(session.catalog);
+    return await withRemoteClient(async (client, runtime) => {
+      storage = { home: runtime.paths.home };
+      const projectList = await remoteProjectsOnClient(client), saved = (await registry()).filter(p => p.host_id === targetHost());
+      const candidates = projectList.filter(p => p.id === selector || p.name === selector || saved.some(s => (s.project_id === selector || s.name === selector) && s.roots.length === p.roots.length && s.roots.every(root => p.roots.some(r => samePath(root, r.path)))));
+      if (candidates.length !== 1) throw failure("Select exactly one live remote project by ID or name.", candidates.length ? "PROJECT_AMBIGUOUS" : "PROJECT_NOT_FOUND");
+      const project = candidates[0], aliases = saved.filter(p => p.roots.length === project.roots.length && p.roots.every(root => project.roots.some(r => samePath(root, r.path))));
+      if (aliases.length !== 1) throw failure("Cannot uniquely map the live project to a Desktop remote registration.", "DESKTOP_PROJECT_MAPPING_UNVERIFIED");
+      const selected = aliases[0], title = settings.title ?? [...prompt.trim().replace(/\s+/gu, " ")].slice(0, 80).join("");
+      receipt = { schema: 4, creation_mode: "remote-native", attempt_id: attemptId, native_call_id: attemptId, ...hostFields(), project_id: project.id, desktop_project_id: selected.project_id,
+        project_name: project.name, cwd: project.roots[0].path, runtime_workspace_roots: project.roots.map(root => root.path), title, context_thread_id: session.context.threadId,
+        context_turn_id: session.context.turnId, creation_status: "not_created", sent: false, delivery_status: "not_sent", verification_status: "not_started",
+        prompt_sha256: createHash("sha256").update(prompt).digest("hex"), message_characters: [...prompt].length, dry_run: !!options.dryRun };
+      if (options.dryRun) return receipt;
+      receipt.receipt_path = storePath("creations", attemptId, runtime.paths.home);
+      const write = value => writeRecord("creations", attemptId, value, { home: runtime.paths.home });
+      await write({ ...receipt, creation_status: "dispatching" });
+      // Recheck roots/registry before the single native creation dispatch.
+      const current = await remoteProjectsOnClient(client), registrations = await registry();
+      if (JSON.stringify(current.find(p => p.id === project.id)) !== JSON.stringify(project) || !registrations.some(p => p.host_id === targetHost() && JSON.stringify(p) === JSON.stringify(selected))) throw failure("Remote project changed before creation.", "PROJECT_CHANGED");
+      dispatched = true;
+      const result = await session.invoke("create_thread", { prompt, title, target: { type: "project", projectId: selected.project_id, environment: { type: "local" } },
+        ...(settings.model ? { model: settings.model } : {}), ...(settings.thinking ? { thinking: settings.thinking } : {}) }, { callId: attemptId });
+      if (typeof result.threadId === "string") { receipt.thread_id = normalizeThreadId(result.threadId); receipt.actual_host_id = result.hostId;
+        receipt.deep_link = typeof result.hostId === "string" ? threadDeepLink(`codex://threads/${receipt.thread_id}?hostId=${encodeURIComponent(result.hostId)}`) : null; }
+      if (result.hostId !== targetHost() || !receipt.thread_id) throw Object.assign(failure("Creation did not confirm the selected remote host. Inspect the saved returned task; do not retry.", "HOST_MISMATCH"), { uncertain: true });
+      receipt.creation_status = "created"; receipt.sent = accepted = true; receipt.delivery_status = "accepted"; receipt.desktop_subscription = "native-owned";
+      await write(receipt);
+      const thread = (await client.request("thread/read", { threadId: receipt.thread_id, includeTurns: false })).thread;
+      if (thread?.id !== receipt.thread_id || !samePath(thread.cwd, receipt.cwd)) throw failure("Created remote task has unexpected scope.", "CREATION_SCOPE_MISMATCH");
+      if (thread.projectId != null && thread.projectId !== project.id) throw failure("Created task was assigned to a different canonical project. Its assignment was not overwritten.", "PROJECT_CHANGED");
+      if (thread.projectId == null) await client.request("thread/metadata/update", { threadId: receipt.thread_id, projectId: project.id }, { mutation: true });
+      const verified = await verifyRemoteCreationOnClient(client, receipt, session, settings.timeoutMs);
+      Object.assign(receipt, verified); await write(receipt); return receipt;
+    }, dependencies);
+  } catch (error) {
+    Object.assign(error, { attempt_id: attemptId, native_call_id: attemptId, thread_id: receipt?.thread_id, receipt_path: receipt?.receipt_path,
+      creation_status: receipt?.thread_id ? "created" : dispatched && error.uncertain !== false ? "unknown" : "not_created", sent: accepted ? true : dispatched && error.uncertain !== false ? null : false,
+      delivery_status: accepted ? "accepted" : dispatched && error.uncertain !== false ? "unknown" : "not_sent" });
+    if (receipt?.receipt_path) try { await writeRecord("creations", attemptId, { ...receipt, creation_status: error.creation_status, sent: error.sent, delivery_status: error.delivery_status, verification_status: "failed", error_code: error.code }, storage); } catch { error.receipt_update_required = true; }
+    throw error;
+  } finally { session?.close(); }
+}
+
+async function verifyRemoteCreationOnClient(client, receipt, session, timeoutMs) {
+  const deadline = Date.now() + Math.min(timeoutMs, 15000);
+  do {
+    const thread = (await client.request("thread/read", { threadId: receipt.thread_id, includeTurns: false })).thread, history = await fetchThread(client, receipt.thread_id);
+    const snapshot = await session.invoke("list_threads", {}), matches = [...(snapshot.threads ?? []), ...(snapshot.pinnedThreads ?? [])].filter(t => t.id === receipt.thread_id);
+    const instruction = initialInstructionText(history, receipt.context_thread_id);
+    if (scopeMatches(thread, receipt) && matches.length === 1 && matches[0].hostId === targetHost() && matches[0].projectId === receipt.desktop_project_id
+      && typeof instruction === "string" && createHash("sha256").update(instruction).digest("hex") === receipt.prompt_sha256) {
+      return { verification_status: "verified", initial_instruction: "verified", desktop_project_membership: "verified", app_server_project_membership: "verified", turn_id: history.turns[0]?.id,
+        observed_runtime_workspace_roots: thread.environments.find(item => item.environmentId === "local").runtimeWorkspaceRoots };
+    }
+    if (Date.now() >= deadline) break; await delay(250);
+  } while (true);
+  throw failure("Created task exists but scope, Desktop membership or initial instruction is not yet verified. Use thread verify; never recreate it.", "CREATION_VERIFICATION_FAILED");
+}
+
+export async function verifyRemoteProjectThread(attemptId, options = {}, dependencies = {}) {
+  requirePairedManagement(); normalizeThreadId(attemptId);
+  return withStoreLock(`creation-${attemptId}`, async () => {
+    const receipt = await readRecord("creations", attemptId);
+    if (receipt?.schema !== 4 || receipt.creation_mode !== "remote-native" || receipt.host_id !== targetHost() || receipt.remote_transport !== "paired"
+      || receipt.creation_status !== "created" || receipt.delivery_status !== "accepted" || !receipt.thread_id || !/^[a-f0-9]{64}$/.test(receipt.prompt_sha256 ?? "")) throw failure("A matching created remote receipt is required.", "CREATION_RECEIPT_UNVERIFIED");
+    let session;
+    const history = status => [...(receipt.verification_history ?? []), { checked_at: new Date().toISOString(), status,
+      previous_status: receipt.verification_status, source: "desktop-and-remote-read-only" }];
+    try {
+      session = await (dependencies.desktop ?? remoteDesktopSession)({ contextThread: receipt.context_thread_id, ...options });
+      return await withRemoteClient(async client => {
+        const result = { ...receipt, ...await verifyRemoteCreationOnClient(client, receipt, session, options.timeoutMs ?? 120000), verification_history: history("verified") };
+        delete result.error_code;
+        await writeRecord("creations", attemptId, result); return result;
+      }, dependencies);
+    } catch (error) {
+      const failed = { ...receipt, verification_status: "failed", error_code: error.code ?? "CREATION_VERIFICATION_FAILED", verification_history: history("failed") };
+      delete failed.desktop_project_membership; delete failed.app_server_project_membership; delete failed.initial_instruction;
+      delete failed.observed_runtime_workspace_roots;
+      try { await writeRecord("creations", attemptId, failed); } catch { error.receipt_update_required = true; }
+      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: receipt.receipt_path });
+      throw error;
+    } finally { session?.close(); }
+  });
+}

package/src/remote.mjs

@@ -0,0 +1,132 @@
+import { discoverRuntime } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+import { readSendState } from "./app-server.mjs";
+import { discoverNativeEndpoint, nativeToolJson } from "./native-rpc.mjs";
+import { inspectNativeCommandProtocol, nativeOnAppServer } from "./native-command.mjs";
+import { parseThreadTarget } from "./thread-id.mjs";
+import { targetHost, targetContext, remoteReadOnly } from "./target.mjs";
+import { assertRuntimeOperation } from "./compatibility.mjs";
+
+const failure = (message, code = "REMOTE_PROTOCOL_ERROR") => Object.assign(new Error(message), { code });
+
+export function validateRemoteCatalog(catalog) {
+  const schema = catalog?.tools?.find(tool => tool.namespace === "codex_app" && tool.name === "read_thread")?.inputSchema;
+  if (schema?.properties?.threadId?.type !== "string" || schema.properties.hostId?.type !== "string"
+    || schema.properties.cursor?.type !== "string" || schema.properties.turnLimit?.maximum !== 10
+    || schema.properties.includeOutputs?.type !== "boolean" || schema.properties.maxOutputCharsPerItem?.maximum !== 20000) {
+    throw failure("Desktop does not expose the required remote read schema.", "REMOTE_READ_UNSUPPORTED");
+  }
+}
+
+function pageThread(page, threadId, hostId) {
+  if (page?.thread?.id !== threadId || page.thread.hostId !== hostId || page.thread.kind !== "codex") {
+    throw failure("Desktop returned a different task or host. No local fallback is allowed.", "HOST_MISMATCH");
+  }
+  if (!["active", "idle", "notLoaded", "systemError"].includes(page.thread.status?.type)
+    || !Array.isArray(page.turns) || page.turns.length > 10 || page.page?.order !== "newest_first"
+    || typeof page.page.hasMore !== "boolean" || (page.page.hasMore && (typeof page.page.nextCursor !== "string" || !page.page.nextCursor || page.page.nextCursor.length > 16384 || !page.turns.length))) {
+    throw failure("Desktop returned invalid remote history pagination.");
+  }
+  return { id: threadId, name: page.thread.title, cwd: page.thread.cwd, status: page.thread.status, turns: [], observationSource: "desktop-native-public-history" };
+}
+
+function publicOutput(output) {
+  if (output == null) return "";
+  if (typeof output.text !== "string" || typeof output.truncated !== "boolean") throw failure("Desktop returned an invalid public output projection.");
+  return output.text + (output.truncated ? "\n[truncated by Desktop]" : "");
+}
+
+function publicTurn(turn) {
+  if (typeof turn?.id !== "string" || !turn.id || typeof turn.status !== "string" || !Array.isArray(turn.items)) throw failure("Desktop returned an incomplete remote turn.");
+  return { ...turn, items: turn.items.map(item => {
+    if (typeof item?.id !== "string" || !item.id || typeof item.type !== "string"
+      || (item.type === "userMessage" && (!Array.isArray(item.content) || item.content.some(part => part.type === "text" && typeof part.text !== "string")))) throw failure("Desktop returned an incomplete public item.");
+    return item.type === "commandExecution" ? { ...item, aggregatedOutput: publicOutput(item.output) }
+      : item.type === "fileChange" ? { ...item, changes: item.changes.map(change => ({ ...change, diff: publicOutput(change.diff) })) } : item;
+  }) };
+}
+
+// Adapt Desktop's public, paged native reads to the existing observation code.
+// No raw remote socket, credential copying, implicit resume or mutation API.
+export function remoteReadClient(invoke, hostId, close = () => {}) {
+  let first;
+  const read = async (threadId, cursor) => {
+    const page = await invoke("read_thread", { threadId, hostId, ...(cursor ? { cursor } : {}), turnLimit: 10, includeOutputs: true, maxOutputCharsPerItem: 20000 });
+    pageThread(page, threadId, hostId);
+    return page;
+  };
+  return {
+    close,
+    async request(method, params = {}, options = {}) {
+      if (method !== "thread/read" || options.mutation) throw remoteReadOnly();
+      if (!params.includeTurns) {
+        first = await read(params.threadId);
+        return { thread: pageThread(first, params.threadId, hostId) };
+      }
+      let page = first?.thread.id === params.threadId ? first : await read(params.threadId); first = undefined;
+      const thread = pageThread(page, params.threadId, hostId), turns = [], ids = new Set(), cursors = new Set();
+      for (let count = 0; count < 100; count++) {
+        for (const turn of page.turns) {
+          if (ids.has(turn.id)) throw failure("Remote history changed or repeated a turn. Read again.", "OBSERVATION_CHANGED");
+          ids.add(turn.id); turns.push(publicTurn(turn));
+        }
+        if (!page.page.hasMore) return { thread: { ...thread, turns: turns.reverse() } };
+        if (count === 99) throw failure("Remote history exceeded 100 pages; no partial snapshot was returned.", "REMOTE_HISTORY_LIMIT");
+        const cursor = page.page.nextCursor;
+        if (cursors.has(cursor)) throw failure("Desktop repeated a remote history cursor.");
+        cursors.add(cursor); page = await read(params.threadId, cursor);
+      }
+      throw failure("Remote history exceeded 100 pages; no partial snapshot was returned.", "REMOTE_HISTORY_LIMIT");
+    },
+  };
+}
+
+export function remoteObservationConnection({ hostId = targetHost(), contextThread = targetContext() ?? process.env.CODEX_THREAD_ID } = {}, {
+  discover = discoverRuntime, connect = RpcClient.connect, endpoint = discoverNativeEndpoint,
+  inspectCommand = inspectNativeCommandProtocol, native = nativeOnAppServer, caller = readSendState,
+} = {}) {
+  let selected;
+  return {
+    async discover(home) {
+      if (!contextThread) throw failure("Remote reads require a real local caller. Run inside Codex or pass --context-thread <LOCAL-THREAD-ID>.", "REMOTE_CONTEXT_REQUIRED");
+      const source = parseThreadTarget(contextThread);
+      if (source.hostId !== undefined && source.hostId !== "local") throw failure("--context-thread must identify a local caller.", "REMOTE_CONTEXT_INVALID");
+      const runtime = await discover(home);
+      assertRuntimeOperation(runtime.state, "read");
+      if (selected && (selected.paths.socket !== runtime.paths.socket || selected.state.instance !== runtime.state.instance)) throw failure("The selected shared runtime changed during remote observation.", "RUNTIME_CHANGED");
+      selected = runtime;
+      return { paths: runtime.paths, state: { native_observation_only: true, remote_host_id: hostId, cli_version: runtime.state.cli_version } };
+    },
+    async connect(socket, options) {
+      if (!selected || socket !== selected.paths.socket) throw failure("Remote discovery is required before connection.");
+      const local = await connect(socket, { ...options, timeoutMs: 35000 });
+      let closed = false;
+      const close = () => {
+        if (closed) return;
+        closed = true; options?.signal?.removeEventListener("abort", close); local.close();
+      };
+      options?.signal?.addEventListener("abort", close, { once: true });
+      if (options?.signal?.aborted) close();
+      try {
+        const nativeEndpoint = await endpoint(selected.state);
+        await inspectCommand(selected.state);
+        const source = await caller(local, parseThreadTarget(contextThread).threadId), turn = source.turns.at(-1);
+        if (!turn?.id || source.ephemeral || source.environments?.some(environment => environment.environmentId !== "local")) throw failure("Remote reads require a persisted local caller with a stored turn.", "REMOTE_CONTEXT_INVALID");
+        const context = { threadId: source.id, turnId: turn.id };
+        validateRemoteCatalog(await native(local, nativeEndpoint, "catalog", undefined, undefined, { timeoutMs: 30000 }));
+        const invoke = async (action, args) => {
+          const current = await discover(selected.paths.home);
+          if (current.paths.socket !== selected.paths.socket || current.state.instance !== selected.state.instance) throw failure("Runtime changed during remote observation.", "RUNTIME_CHANGED");
+          try { return nativeToolJson(await native(local, nativeEndpoint, action, args, context, { timeoutMs: 30000 })); }
+          catch (error) {
+            error.uncertain = false;
+            if (error.code === "NATIVE_TIMEOUT") error.code = "TIMEOUT";
+            else if (["NATIVE_CONNECTION_FAILED", "NATIVE_CONNECTION_CLOSED"].includes(error.code)) error.code = "CONNECTION_FAILED";
+            throw error;
+          }
+        };
+        return remoteReadClient(invoke, hostId, close);
+      } catch (error) { close(); throw error; }
+    },
+  };
+}

package/src/resource.mjs

@@ -1,8 +1,9 @@
 import { randomUUID } from "node:crypto";
 import { digest } from "./observe.mjs";
 import { readRecord, writeRecord, listRecords, withStoreLock } from "./store.mjs";
-import { normalizeThreadId } from "./thread-id.mjs";
+import { normalizeTaskId } from "./task-id.mjs";
 import { runCommand } from "./runner.mjs";
+import { targetHost } from "./target.mjs";
 
 function resourceKey(name) {
   if (!name?.trim() || name.length > 200 || /[\r\n\x00-\x1f]/.test(name)) throw new Error("Resource name must be a non-empty single line (up to 200 characters).");
@@ -19,7 +20,7 @@ export async function resourceStatus(name, { now = Date.now, ...storage } = {})
 export async function acquireResource(name, { owner, ttlMs = 600000, reason = "", condition = "", threadId, now = Date.now, ...storage }) {
   const key = resourceKey(name); validTtl(ttlMs);
   if (!owner?.trim()) throw new Error("--owner is required (for example claude-code or codex).");
-  if (threadId) threadId = normalizeThreadId(threadId);
+  if (threadId) threadId = normalizeTaskId(threadId);
   return withStoreLock(`resource-${key}`, async () => {
     const current = await readRecord("resources", key, storage);
     if (leaseState(current, now()) === "held") throw Object.assign(new Error(`Resource is held by ${current.owner} until ${current.expires_at}.`), { code: "RESOURCE_BUSY" });
@@ -53,18 +54,19 @@ export async function listResources({ now = Date.now, ...storage } = {}) {
   return (await listRecords("resources", storage)).map(lease => ({ name: lease.name, state: leaseState(lease, now()), lease })).sort((a, b) => a.name.localeCompare(b.name));
 }
 
-export async function runWithResource(name, argv, { timeoutMs = 0, cwd = process.cwd(), ttlMs = 600000, ...options }) {
+export async function runWithResource(name, argv, { timeoutMs = 0, cwd = targetHost() === "local" ? process.cwd() : undefined, ttlMs = 600000, execBackend, remoteShell, supervisor, connection, ...options }, { execute = runCommand } = {}) {
   if (!argv.length || !Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 86400000) throw new Error("A command and valid --timeout-ms are required.");
   const lease = await acquireResource(name, { ...options, ttlMs }), controller = new AbortController();
-  let timer, renewal = Promise.resolve(), stopped = false, leaseError = null, released = false, result;
+  let timer, renewal = Promise.resolve(), stopped = false, leaseError = null, released = false, result, uncertain = false;
   const schedule = () => { timer = setTimeout(() => {
     renewal = renewResource(name, lease.token, { ...options, ttlMs }).then(() => { if (!stopped) schedule(); }).catch(e => { leaseError = e.message; controller.abort(); });
   }, Math.floor(ttlMs / 3)); };
   schedule();
-  try { result = await runCommand(argv, { cwd, timeoutMs, signal: controller.signal }); }
+  try { result = await execute(argv, { cwd, timeoutMs, signal: controller.signal, execBackend, remoteShell, threadId: options.threadId, supervisor, connection }); }
+  catch (error) { uncertain = !!error.uncertain; if (uncertain) { error.resource = name; error.lease_retained = true; error.remote_execution_status = "unknown"; } throw error; }
   finally {
     stopped = true; clearTimeout(timer); await renewal;
-    try { await releaseResource(name, lease.token, options); released = true; } catch (e) { leaseError ??= e.message; }
+    if (!uncertain) try { await releaseResource(name, lease.token, options); released = true; } catch (e) { leaseError ??= e.message; }
   }
   return { resource: name, owner: lease.owner, ...result, lease_error: leaseError, released, valid: !leaseError && result.exit_code === 0 && !result.error && !result.timed_out };
 }

package/src/runner.mjs

@@ -1,7 +1,12 @@
 import { spawn } from "node:child_process";
+import { targetHost } from "./target.mjs";
+import { runRemoteCommand, runRemoteShellCommand } from "./remote-io.mjs";
 
-export function runCommand(argv, { cwd, timeoutMs = 0, onStart = async () => {}, signal: abortSignal } = {}) {
+export function runCommand(argv, { cwd, timeoutMs = 0, onStart = async () => {}, signal: abortSignal, execBackend = "app-server", threadId, remoteShell, supervisor, connection } = {}) {
   if (!argv.length || !argv[0] || !Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 86400000) throw new Error("A command and timeout-ms between 0 and 86400000 are required.");
+  if (!["app-server", "thread-shell"].includes(execBackend)) throw new Error("--exec-backend must be app-server or thread-shell.");
+  if (targetHost() !== "local") return (execBackend === "thread-shell" ? runRemoteShellCommand : runRemoteCommand)(argv, { cwd, timeoutMs, onStart, signal: abortSignal, threadId, shell: remoteShell, supervisor, connection });
+  if (execBackend !== "app-server") throw new Error("thread-shell is an explicit remote execution backend.");
   return new Promise((resolve, reject) => {
     const started = new Date().toISOString();
     let output = "", truncated = false, timedOut = false, failure, killer, timer, startUpdate = Promise.resolve(), closed = false;

package/src/runtime.mjs

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, rename, rm, writeFile, realpath } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { inspectAppServerSocket } from "./socket-endpoint.mjs";
 
 const runtimeFailure = (message, code) => Object.assign(new Error(message), { code });
 
@@ -75,9 +76,10 @@ export async function discoverRuntime(home) {
     if (!isAlive(state.pid) || !isAlive(state.server_pid) || !state.desktop_connected) {
       throw runtimeFailure("Shared App Server is not ready. Finish current tasks, quit Desktop, then run: codexteer desktop start", "RUNTIME_NOT_READY");
     }
-    await checkOwned(paths.socket, "socket");
-    return { paths, state };
+    const endpoint = await inspectAppServerSocket(paths.socket);
+    return { paths: { ...paths, socket: endpoint.socket }, state };
   } catch (error) {
+    if (error.code === "SOCKET_UNSAFE") throw runtimeFailure(error.message, "RUNTIME_UNSAFE");
     if (error.code === "ENOENT") throw runtimeFailure("Shared App Server is unavailable. Finish current tasks, quit Desktop, then run: codexteer desktop start", "RUNTIME_UNAVAILABLE");
     if (["EACCES", "EPERM"].includes(error.code)) throw runtimeFailure("Cannot inspect the shared App Server runtime. Check access permissions.", "PERMISSION_DENIED");
     throw error;

package/src/socket-endpoint.mjs

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const unsafe = () => Object.assign(new Error("App Server socket has unsafe ownership, permissions, file type, or link target."), { code: "SOCKET_UNSAFE" });
+const identity = info => [info.dev, info.ino, info.ctimeMs];
+const same = (a, b) => JSON.stringify(identity(a)) === JSON.stringify(identity(b));
+
+function checkSocket(info) {
+  if (info.uid !== process.getuid() || (info.mode & 0o077) || !info.isSocket()) throw unsafe();
+}
+
+// Callers validate the advertised path's private parent directories separately.
+// Codex 0.155 publishes a deterministic alias to a protected socket:
+// codex-rs/app-server-transport/src/transport/unix_socket.rs and uds/src/daemon_directory.rs.
+// Accept only that layout; never follow arbitrary links or repair permissions.
+export async function inspectAppServerSocket(file) {
+  const advertised = await fs.lstat(file);
+  if (!advertised.isSymbolicLink()) {
+    checkSocket(advertised);
+    return { socket: file, fingerprint: [identity(advertised)] };
+  }
+  // Link permission bits do not describe access to its target.
+  if (advertised.uid !== process.getuid()) throw unsafe();
+  const canonical = path.join(await fs.realpath(path.dirname(file)), path.basename(file));
+  // Upstream deliberately ignores TMPDIR, HOME and CODEX_HOME for this root.
+  const directory = path.join(await fs.realpath("/tmp"), `codex-daemon-${process.getuid()}`);
+  const socket = path.join(directory, createHash("sha256").update(canonical).digest("hex"));
+  if (await fs.readlink(file) !== socket) throw unsafe();
+  const parent = await fs.lstat(directory);
+  if (parent.uid !== process.getuid() || !parent.isDirectory() || (parent.mode & 0o777) !== 0o700) throw unsafe();
+  const target = await fs.lstat(socket);
+  checkSocket(target); // lstat rejects a second link, even if it ends at a socket.
+  const currentParent = await fs.lstat(directory);
+  if (!same(advertised, await fs.lstat(file)) || await fs.readlink(file) !== socket
+    || parent.dev !== currentParent.dev || parent.ino !== currentParent.ino
+    || parent.mode !== currentParent.mode || parent.uid !== currentParent.uid) throw unsafe();
+  // Directory timestamps change when unrelated profiles create sockets.
+  return { socket, fingerprint: [identity(advertised), [parent.dev, parent.ino], identity(target)] };
+}