codexteer 0.16.0 → 0.17.0

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)] };
+}

package/src/standalone-create.mjs

@@ -0,0 +1,134 @@
+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 } 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 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])).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(paths.home, threadId, desktopId) && 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/supervise.mjs

@@ -5,10 +5,10 @@ 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 { prepareCodexHome, prepareDeployment } from "./distribution.mjs";
 import { normalizeThreadId } from "./thread-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";
 
@@ -21,31 +21,36 @@ function shellArgument(value) {
   return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
-export async function prepareSupervisorPrompt(threadInput, policy, { agent = "claude", connection = "shared" } = {}) {
+export async function prepareSupervisorPrompt(threadInput, policy, { agent = "claude", connection = "shared", usePathCli = false } = {}) {
   const threadId = normalizeThreadId(threadInput);
   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}`;
+  if (usePathCli) {
+    return { ...pathSupervisorPrompt(threadId, `codexteer ${sessionOptions}`, policy, supervisor, { usePathCli: true }),
+      cli_mode: "path", deployment: null, node: null, 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 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 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), deployment, node, supervisor };
+  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" });
 }
 
-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 };
+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); }
   finally {

package/src/thread-create.mjs

@@ -0,0 +1,127 @@
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { discoverRuntime } 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 { 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 { writeRecord, storePath } from "./store.mjs";
+import { createStandaloneProjectThread } from "./standalone-create.mjs";
+
+const failure = (message, code = "CREATION_FAILED") => Object.assign(new Error(message), { code });
+
+export function creationOptions(options = {}) {
+  if (["cwd", "permissions", "sandbox", "approvalPolicy", "approvalsReviewer", "viaThread"].some(key => options[key] !== undefined)) throw failure("Native creation uses Desktop's project and permission settings. cwd/permission overrides and --via-thread are unsupported.", "INVALID_CREATION_OPTIONS");
+  for (const key of ["title", "model"]) if (options[key] !== undefined && (typeof options[key] !== "string" || !options[key].trim())) throw failure(`${key} must not be empty.`, "INVALID_CREATION_OPTIONS");
+  if (options.thinking !== undefined && !["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"].includes(options.thinking)) throw failure("Invalid --thinking.", "INVALID_CREATION_OPTIONS");
+  const timeoutMs = options.timeoutMs ?? 120000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000) throw failure("--timeout-ms must be 1000..600000.", "INVALID_CREATION_OPTIONS");
+  return { timeoutMs, ...Object.fromEntries(["title", "model", "thinking"].filter(key => options[key] !== undefined).map(key => [key, options[key]])) };
+}
+
+export function validateNativeCreationCatalog(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") };
+}
+
+export async function createProjectThread(selector, prompt, options = {}, dependencies = {}) {
+  const settings = creationOptions(options);
+  if (typeof selector !== "string" || !selector.trim()) throw failure("--project is required.", "PROJECT_REQUIRED");
+  if (typeof prompt !== "string" || !prompt.trim()) throw failure("An initial instruction is required.", "INITIAL_INSTRUCTION_REQUIRED");
+  // An environment variable must not silently turn standalone user work into
+  // delegated work or inherit another task's permissions.
+  if (options.contextThread === undefined) return createStandaloneProjectThread(selector, prompt, { ...settings, dryRun: !!options.dryRun }, dependencies);
+  const {
+  discover = discoverRuntime, connect = RpcClient.connect, aliases = projectAliases,
+  endpoint = discoverNativeEndpoint, inspectEndpoint = inspectNativeEndpoint, inspectCommand = inspectNativeCommandProtocol, native,
+  workspace = projectWorkspace, caller = readSendState, history = fetchThread,
+  membership = desktopMembership, write = writeRecord, sleep = delay,
+  } = dependencies;
+  const sourceId = options.contextThread;
+  const contextId = normalizeThreadId(sourceId), attemptId = randomUUID();
+  let client, receipt, storage, dispatched = false, accepted = false;
+  try {
+    const { paths, state } = await discover(); storage = { home: paths.home };
+    assertRuntimeOperation(state, "read");
+    const nativeEndpoint = await endpoint(state);
+    const commandProtocol = await inspectCommand(state);
+    client = compatibleClient(await connect(paths.socket, { timeoutMs: settings.timeoutMs + 5000 }), state);
+    const invokeNative = native ?? ((...args) => nativeOnAppServer(client, ...args));
+    const source = await caller(client, contextId), turn = source.turns.at(-1);
+    if (!turn?.id || source.ephemeral || source.environments?.some(environment => environment.environmentId !== "local")) throw failure("A local, persisted caller chat with a stored turn is required.", "CREATION_CONTEXT_INVALID");
+    const context = { threadId: contextId, turnId: turn.id }, nativeOptions = { timeoutMs: settings.timeoutMs };
+    const protocol = { ...validateNativeCreationCatalog(await invokeNative(nativeEndpoint, "catalog", undefined, undefined, nativeOptions)), command: commandProtocol };
+    const mapping = await aliases(paths.home), project = resolveProject(await projectsOnClient(client), selector, mapping), scope = await workspace(project);
+    const listNative = async () => {
+      const inventory = nativeToolJson(await invokeNative(nativeEndpoint, "list_projects", {}, context, nativeOptions));
+      if (!Array.isArray(inventory.projects)) throw failure("Desktop returned an invalid project catalog.", "NATIVE_PROTOCOL_ERROR");
+      const matches = inventory.projects.filter(item => item.projectKind === "local" && item.hostId === "local" && (mapping[item.projectId] === project.id || item.projectId === project.id));
+      if (matches.length !== 1 || matches[0].label !== project.name || matches[0].path !== project.roots[0].path) throw failure("Selected App Server project does not match exactly one native Desktop project.", "DESKTOP_PROJECT_MAPPING_UNVERIFIED");
+      return matches[0];
+    };
+    const selected = await listNative();
+    const check = async () => {
+      const current = await discover();
+      if (current.state.instance !== state.instance || current.paths.socket !== paths.socket || current.state.cli_version !== state.cli_version) throw failure("Runtime changed. Inspect the receipt before retrying.", "RUNTIME_CHANGED");
+      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) throw failure("Project source folders changed before creation.", "PROJECT_CHANGED");
+      if ((await listNative()).projectId !== selected.projectId) throw failure("Native project changed before creation.", "PROJECT_CHANGED");
+    };
+    await check();
+    receipt = { schema: 2, creation_mode: "delegated", attempt_id: attemptId, native_call_id: attemptId, project_id: project.id, desktop_project_id: selected.projectId, project_name: project.name,
+      context_thread_id: contextId, context_turn_id: turn.id, cwd: scope.cwd, runtime_workspace_roots: scope.runtimeWorkspaceRoots,
+      title: settings.title ?? null, backend: "desktop-native-rpc", 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: !!options.dryRun };
+    if (options.dryRun) return receipt;
+    receipt.receipt_path = storePath("creations", attemptId, paths.home);
+    await write("creations", attemptId, { ...receipt, creation_status: "dispatching" }, storage);
+    await check();
+    dispatched = true;
+    const args = { prompt, target: { type: "project", projectId: selected.projectId, environment: { type: "local" } }, ...Object.fromEntries(["title", "model", "thinking"].filter(key => settings[key] !== undefined).map(key => [key, settings[key]])) };
+    const raw = await invokeNative(nativeEndpoint, "create_thread", args, context, { ...nativeOptions, callId: attemptId });
+    if (raw.native_request_cleanup_required) receipt.native_request_cleanup_required = true;
+    const result = nativeToolJson(raw);
+    const id = result.threadId ?? (result.status === "created" ? result.conversationId : undefined);
+    if (!id) throw Object.assign(failure("Native creation returned no child ID. Do not retry automatically.", "NATIVE_CREATION_UNKNOWN"), { uncertain: true });
+    const threadId = normalizeThreadId(id);
+    accepted = !!result.threadId || result.firstTurn?.status === "accepted";
+    Object.assign(receipt, { thread_id: threadId, deep_link: threadDeepLink(threadId), creation_status: "created", sent: accepted ? true : null, delivery_status: accepted ? "accepted" : "unknown" });
+    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");
+    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;
+    // Native acceptance can precede the first input's persisted history item.
+    // Wait only for read-side materialization; never repeat create or turn/start.
+    const ready = () => saved.turns?.[0]?.items?.some(item => item.type === "userMessage" || (item.type === "functionCallOutput" && item.namespace === "codex_app" && item.name === "create_thread"));
+    for (let retry = 0; retry < 20 && (!ready() || (settings.title !== undefined && named.name == null)); retry++) {
+      await sleep(250);
+      saved = await history(client, threadId);
+      named = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
+    }
+    if (!initialInstructionMatches(saved, prompt, contextId) || (settings.title !== undefined && named.name !== settings.title)) throw failure("Created child did not preserve the initial instruction/title.", "CREATION_INSTRUCTION_MISMATCH");
+    if (thread.projectId !== project.id) await client.request("thread/metadata/update", { threadId, projectId: project.id }, { mutation: true });
+    if ((await client.request("thread/read", { threadId, includeTurns: false })).thread?.projectId !== project.id) throw failure("Canonical project assignment was not confirmed.", "CREATION_SCOPE_MISMATCH");
+    Object.assign(receipt, { verification_status: "verified", desktop_project_membership: "verified", app_server_project_membership: "verified", initial_instruction: "verified", desktop_subscription: "native-owned" });
+    try { await write("creations", attemptId, receipt, storage); } catch { receipt.receipt_update_required = true; }
+    return receipt;
+  } catch (error) {
+    const created = !!receipt?.thread_id, unknown = !accepted && (created || (dispatched && 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" : unknown ? "unknown" : "not_created", sent: accepted ? true : unknown ? null : false, delivery_status: accepted ? "accepted" : unknown ? "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/wrapper.mjs

@@ -1,7 +1,8 @@
 import { spawn, spawnSync } from "node:child_process";
-import { chmod, stat } from "node:fs/promises";
+import { accessSync, constants as fsConstants, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { once } from "node:events";
 import { setTimeout as delay } from "node:timers/promises";
+import path from "node:path";
 import { claimRuntime } from "./runtime.mjs";
 import { connectSocket } from "./rpc.mjs";
 import { relay } from "./bridge.mjs";
@@ -9,8 +10,61 @@ import { DesktopSubscriptions, serveSubscriptions } from "./subscription.mjs";
 import { VERSION, PACKAGE_NAME } from "./version.mjs";
 import { RUNTIME_PROTOCOL, RUNTIME_CAPABILITIES } from "./compatibility.mjs";
 import { describeDistribution } from "./distribution.mjs";
+import { inspectAppServerSocket } from "./socket-endpoint.mjs";
 
-export const BUNDLED_CLI = "/Applications/ChatGPT.app/Contents/Resources/codex";
+const DESKTOP_RESOURCES = "/Applications/ChatGPT.app/Contents/Resources";
+const LEGACY_BUNDLED_CLI = path.join(DESKTOP_RESOURCES, "codex");
+
+function isWithinDirectory(directory, candidate) {
+  const relative = path.relative(directory, candidate);
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function resolveManifestCli(packageDirectory, resourcesDirectory) {
+  try {
+    const root = realpathSync(packageDirectory);
+    if (!isWithinDirectory(resourcesDirectory, root)) return null;
+    const manifest = JSON.parse(readFileSync(path.join(root, "codex-package.json"), "utf8"));
+    if ((manifest.variant != null && manifest.variant !== "codex")
+      || (manifest.layoutVersion != null && (!Number.isSafeInteger(manifest.layoutVersion) || manifest.layoutVersion < 1))
+      || typeof manifest.entrypoint !== "string" || manifest.entrypoint.length === 0
+      || manifest.entrypoint.includes("\0") || path.isAbsolute(manifest.entrypoint)
+      || manifest.entrypoint.split(/[\\/]/).some(part => part === "" || part === "." || part === "..")) return null;
+
+    const entrypoint = realpathSync(path.resolve(root, manifest.entrypoint));
+    if (!isWithinDirectory(root, entrypoint) || !statSync(entrypoint).isFile()) return null;
+    accessSync(entrypoint, fsConstants.X_OK);
+    return entrypoint;
+  } catch {
+    return null;
+  }
+}
+
+function resolveBundledCli() {
+  try {
+    const resourcesDirectory = realpathSync(DESKTOP_RESOURCES);
+    const packages = readdirSync(resourcesDirectory, { withFileTypes: true })
+      .filter(entry => entry.isDirectory() || entry.isSymbolicLink())
+      .map(entry => path.join(resourcesDirectory, entry.name))
+      .sort();
+    const manifestCli = packages.map(directory => resolveManifestCli(directory, resourcesDirectory)).find(Boolean);
+    if (manifestCli) return manifestCli;
+  } catch {
+    // Fall through to the pre-manifest app layout.
+  }
+
+  try {
+    if (statSync(LEGACY_BUNDLED_CLI).isFile()) {
+      accessSync(LEGACY_BUNDLED_CLI, fsConstants.X_OK);
+      return LEGACY_BUNDLED_CLI;
+    }
+  } catch {
+    // Preserve the legacy path for a useful ENOENT diagnostic at startup.
+  }
+  return LEGACY_BUNDLED_CLI;
+}
+
+export const BUNDLED_CLI = resolveBundledCli();
 export const BUNDLED_NODE = "/Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node";
 const DESKTOP_EXECUTABLE = "/Applications/ChatGPT.app/Contents/MacOS/ChatGPT";
 
@@ -95,6 +149,7 @@ export async function runWrapper(args, { executable = BUNDLED_CLI, env = process
     codex_steer_package: PACKAGE_NAME, codex_steer_version: VERSION, codex_steer_protocol: RUNTIME_PROTOCOL,
     codex_steer_capabilities: RUNTIME_CAPABILITIES,
     distribution_sha256: distribution.sha256,
+    native_tools_pipe: env.CODEX_APP_TOOLS_PIPE_PATH ?? null,
   });
   let child;
   let socket;
@@ -110,14 +165,22 @@ export async function runWrapper(args, { executable = BUNDLED_CLI, env = process
     });
     let spawnError;
     child.on("error", error => { spawnError = error; });
+    let endpoint;
+    let socketError;
     for (let i = 0; i < 100; i++) {
       if (interrupted || spawnError || child.exitCode != null || child.signalCode != null) throw new Error("App Server exited during startup.");
-      if (await stat(lease.paths.socket).catch(() => null)) break;
+      try {
+        endpoint = await inspectAppServerSocket(lease.paths.socket);
+        break;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+        socketError = error;
+      }
       await delay(100);
     }
-    await chmod(lease.paths.socket, 0o600);
+    if (!endpoint) throw socketError ?? new Error("App Server socket did not become ready during startup.");
     await lease.update({ server_pid: child.pid });
-    socket = await connectSocket(lease.paths.socket);
+    socket = await connectSocket(endpoint.socket);
     subscriptions = new DesktopSubscriptions(socket);
     stopSubscriptions = await serveSubscriptions(lease.paths.control, subscriptions);
     let initId;