codexteer 0.16.0 → 0.18.0

package/src/remote-device.mjs

@@ -0,0 +1,202 @@
+import { randomUUID } from "node:crypto";
+import { discoverRuntime } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+import { authIdentity, controlFailure } from "./remote-control-auth.mjs";
+import { RemoteControlSocket } from "./remote-control-socket.mjs";
+import { deviceKey, dedicatedConnectionProof } from "./remote-device-key.mjs";
+import { readDevice, saveDevice, withDeviceLock, dedicatedEnrollment, keySelection } from "./remote-device-store.mjs";
+import { prepareKeychainRuntime, keychainOperation } from "./remote-keychain.mjs";
+import { ENROLL_START, ENROLL_FINISH, PAIR_PATH, deviceIdentity, enrollmentPayload, validateRegistration, verifyEnrollmentProof, officialDeviceRequest } from "./remote-device-protocol.mjs";
+import { stepUpLogin, validateStepUpToken } from "./remote-device-login.mjs";
+import { REMOTE_CLIENT_INFO } from "./remote-client-info.mjs";
+
+export async function withDeviceAccount(operation, { discover = discoverRuntime, connect = RpcClient.connect, request = officialDeviceRequest } = {}) {
+  const runtime = await discover(), local = await connect(runtime.paths.socket);
+  try {
+    const identity = authIdentity(await local.request("getAuthStatus", { includeToken: true, refreshToken: false }));
+    const current = async () => {
+      const latest = await discover(runtime.paths.home), status = await local.request("getAuthStatus", { includeToken: true, refreshToken: false });
+      if (latest.state.instance !== runtime.state.instance || latest.paths.socket !== runtime.paths.socket || JSON.stringify(authIdentity(status)) !== JSON.stringify(identity)) {
+        throw controlFailure("The selected account or runtime changed. No device operation was sent to another account.", "REMOTE_IDENTITY_CHANGED");
+      }
+      return { identity, token: status.authToken };
+    };
+    return await operation({ home: runtime.paths.home, identity, current,
+      request: async (route, options) => request(await current(), route, options) });
+  } finally { local.close(); }
+}
+
+export function deviceStatus(record) {
+  return { credential_source: "codexteer-dedicated", registration_status: record?.phase ?? "not_enrolled", client_id: record?.clientId ?? null,
+    controller_name: REMOTE_CLIENT_INFO.controller_name,
+    key_protection: record?.key?.protectionClass ?? null, key_provider: record?.key_provider ?? "openai-native", paired_host_ids: record?.pairings.map(pair => pair.host_id) ?? [],
+    pairing_unknown: record?.pairing_unknown ?? false, instruction_sent: false };
+}
+
+// Read only our registered public metadata; never expose other controllers,
+// account identities or last-seen location from the account-wide response.
+export async function deviceIdentityInfo(context) {
+  const record = await readDevice(context.home, context.identity);
+  dedicatedEnrollment(record, context.identity);
+  const seen = new Set(); let cursor;
+  for (let page = 0; page < 100; page++) {
+    const result = await context.request(`/wham/remote/control/clients?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`, { method: "GET" });
+    if (!Array.isArray(result?.items)) throw controlFailure("Invalid controller metadata response.", "REMOTE_DEVICE_METADATA_INVALID");
+    const own = result.items.find(item => item?.client_id === record.clientId);
+    if (own) {
+      const text = key => typeof own[key] === "string" && own[key].length <= 512 ? own[key] : null;
+      const display = text("display_name");
+      return { ...deviceStatus(record), server_display_name: display, server_platform: text("platform"), server_device_model: text("device_model"),
+        name_matches: display === REMOTE_CLIENT_INFO.controller_name, custom_name_update: "unsupported" };
+    }
+    if (result.cursor == null) throw controlFailure("Dedicated controller was not present in the account list.", "REMOTE_DEVICE_METADATA_NOT_FOUND");
+    if (typeof result.cursor !== "string" || !result.cursor || result.cursor.length > 4096 || seen.has(result.cursor)) throw controlFailure("Invalid controller metadata pagination.", "REMOTE_DEVICE_METADATA_INVALID");
+    seen.add(result.cursor); cursor = result.cursor;
+  }
+  throw controlFailure("Controller metadata exceeded its pagination limit.", "REMOTE_DEVICE_METADATA_INVALID");
+}
+
+export async function readPairingCode(input = process.stdin) {
+  if (!input.isTTY) {
+    let text = "";
+    for await (const chunk of input) { text += chunk.toString("utf8"); if (text.length > 256) throw controlFailure("Invalid pairing code input.", "REMOTE_PAIR_INPUT_INVALID"); }
+    return text.trim();
+  }
+  return new Promise((resolve, reject) => {
+    let text = "";
+    const finish = (error, result) => { input.removeListener("data", data); input.removeListener("end", ended); input.removeListener("error", failed); input.setRawMode(false); input.pause(); error ? reject(error) : resolve(result); };
+    const failed = () => finish(controlFailure("Pairing code input was cancelled.", "REMOTE_PAIR_INPUT_INVALID"));
+    const ended = () => finish(null, text.trim());
+    const data = chunk => {
+      for (const char of chunk.toString("utf8")) {
+        if (char === "\u0003") return failed();
+        if (["\n", "\r", "\u0004"].includes(char)) return ended();
+        if (["\u007f", "\b"].includes(char)) text = text.slice(0, -1);
+        else if (/^[A-Za-z0-9-]$/.test(char)) text += char;
+        else return failed();
+        if (text.length > 128) return failed();
+      }
+    };
+    input.setRawMode(true); input.on("data", data); input.once("end", ended); input.once("error", failed); input.resume();
+  });
+}
+
+export async function prepareDevice(context, { key = deviceKey, provider = "openai-native", prepare = prepareKeychainRuntime } = {}) {
+  const { home, identity } = context;
+  if (!["openai-native", "keychain"].includes(provider)) throw controlFailure("--key-provider must be openai-native or keychain.", "REMOTE_KEY_PROVIDER_INVALID");
+  return withDeviceLock(home, identity, async () => {
+    const existing = await readDevice(home, identity);
+    if (existing && !(existing.phase === "key-failed" && !existing.key && !existing.clientId && existing.key_provider !== provider)) {
+      if (!["prepared", "enrolled"].includes(existing.phase)) throw controlFailure("A dedicated key operation is unresolved. Inspect the saved phase before creating another key.", "REMOTE_ENROLLMENT_PENDING");
+      if ((existing.key_provider ?? "openai-native") !== provider) throw controlFailure("The dedicated key already uses another provider. It was not replaced.", "REMOTE_KEY_PROVIDER_MISMATCH");
+      await key("inspect", { enrollment: { ...existing.key, ...keySelection(existing) }, home, identity }); return deviceStatus(existing);
+    }
+    await context.current();
+    const record = { schema: 1, accountId: identity.accountId, accountUserId: identity.accountUserId, phase: "creating-key",
+      operation_id: randomUUID(), pairings: [], key_provider: provider, created_at: new Date().toISOString() };
+    if (provider === "keychain") { record.key_runtime = await prepare(home, identity); record.candidate_key_id = `codexteer_${randomUUID()}`; }
+    await saveDevice(home, identity, record);
+    try { record.key = await key("create", { provider, home, identity, runtime: record.key_runtime, keyId: record.candidate_key_id }); }
+    catch (error) { if (error.key_creation_rejected) { record.phase = "key-failed"; record.key_error = "MISSING_ENTITLEMENT"; await saveDevice(home, identity, record); } throw error; }
+    record.phase = "prepared"; await saveDevice(home, identity, record);
+    return deviceStatus(record);
+  });
+}
+
+export async function recoverDeviceKey(context) {
+  const { home, identity } = context;
+  return withDeviceLock(home, identity, async () => {
+    const record = await readDevice(home, identity);
+    if (record?.phase !== "creating-key" || record.key_provider !== "keychain" || !record.candidate_key_id || record.clientId) throw controlFailure("No recoverable key-only preparation exists.", "REMOTE_ENROLLMENT_PENDING");
+    record.key = await keychainOperation("recover", { home, identity, runtime: record.key_runtime, keyId: record.candidate_key_id });
+    record.phase = "prepared"; await saveDevice(home, identity, record); return deviceStatus(record);
+  });
+}
+
+export async function enrollDevice(context, { login = stepUpLogin, key = deviceKey, progress } = {}) {
+  const { home, identity } = context;
+  return withDeviceLock(home, identity, async () => {
+    const existing = await readDevice(home, identity);
+    if (existing?.phase === "enrolled") return deviceStatus(existing);
+    if (existing && existing.phase !== "prepared") throw controlFailure("An unresolved registration already exists. Use remote verify; do not create another device automatically.", "REMOTE_ENROLLMENT_PENDING");
+    // Authenticate before any key or server registration exists. Only the
+    // official fresh enrollment token stays in this process's memory.
+    const stepUp = validateStepUpToken(await login(identity, { progress }), identity);
+    await context.current();
+    let record = existing ? { ...existing, phase: "starting" } : { schema: 1, accountId: identity.accountId, accountUserId: identity.accountUserId, phase: "starting",
+      operation_id: randomUUID(), pairings: [], created_at: new Date().toISOString() };
+    await saveDevice(home, identity, record);
+    const start = await context.request(ENROLL_START, { body: {} });
+    if (typeof start?.client_id !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(start.client_id)
+      || ![identity.accountUserId, identity.authUserId].includes(start.account_user_id)) {
+      throw controlFailure("Registration start was not confirmed for the current account. Inspect before retrying.", "REMOTE_ENROLLMENT_UNKNOWN");
+    }
+    record = { ...record, clientId: start.client_id, serverAccountUserId: start.account_user_id, phase: "creating-key" };
+    await saveDevice(home, identity, record);
+    record.key ??= await key("create"); record.phase = "key-created";
+    await saveDevice(home, identity, record);
+    const enrolled = { ...record.key, clientId: record.clientId, accountUserId: record.serverAccountUserId, ...keySelection(record) };
+    enrollmentPayload(start.device_key_challenge, enrolled, ENROLL_FINISH);
+    const proof = verifyEnrollmentProof(await key("enrollment-proof", { home, identity, enrollment: enrolled, challenge: start.device_key_challenge, path: ENROLL_FINISH }), start.device_key_challenge, enrolled);
+    record.phase = "finish-unknown"; await saveDevice(home, identity, record);
+    const result = await context.request(ENROLL_FINISH, { body: { client_id: enrolled.clientId, step_up_token: stepUp,
+      device_identity: deviceIdentity(enrolled), device_key_proof: proof } });
+    validateRegistration(result, enrolled);
+    record.phase = "enrolled"; await saveDevice(home, identity, record);
+    return deviceStatus(record);
+  });
+}
+
+export async function pairDevice(context, hostId, code) {
+  if (!/^remote-control:env_[A-Za-z0-9_-]+$/.test(hostId) || typeof code !== "string" || !/^[A-Za-z0-9-]{6,128}$/.test(code)) {
+    throw controlFailure("Pairing requires an explicit Remote Control host and its fresh code via stdin.", "REMOTE_PAIR_INPUT_INVALID");
+  }
+  const { home, identity } = context;
+  return withDeviceLock(home, identity, async () => {
+    const record = await readDevice(home, identity), enrollment = dedicatedEnrollment(record, identity);
+    if (record.pairing_unknown) throw controlFailure("The last pairing has unknown outcome. Use remote verify before another attempt.", "REMOTE_PAIR_UNKNOWN");
+    if (record.pairings.some(pair => pair.host_id === hostId)) return deviceStatus(record);
+    record.pairing_unknown = true; await saveDevice(home, identity, record);
+    let result;
+    try { result = await context.request(PAIR_PATH, { body: { client_id: enrollment.clientId, manual_pairing_code: code } }); }
+    catch (error) { if (error.code === "REMOTE_ENROLLMENT_REJECTED") { record.pairing_unknown = false; await saveDevice(home, identity, record); } throw error; }
+    if (!/^env_[A-Za-z0-9_-]+$/.test(result?.environment_id ?? "")) throw controlFailure("Pairing acknowledgement was invalid. Use remote verify.", "REMOTE_PAIR_UNKNOWN");
+    const actualHost = `remote-control:${result.environment_id}`;
+    record.pairings = [...record.pairings.filter(pair => pair.host_id !== actualHost), { host_id: actualHost, verified_at: new Date().toISOString() }];
+    record.pairing_unknown = false; await saveDevice(home, identity, record);
+    if (actualHost !== hostId) throw controlFailure(`The supplied pairing code belongs to ${actualHost}, not the selected host. No task was opened or sent an instruction.`, "REMOTE_PAIR_HOST_MISMATCH");
+    return deviceStatus(record);
+  });
+}
+
+export async function verifyDevice(context, { key = deviceKey, open = RemoteControlSocket.connect } = {}) {
+  const { home, identity } = context;
+  return withDeviceLock(home, identity, async () => {
+    const record = await readDevice(home, identity);
+    if (!record?.key || !record.clientId || !["enrolled", "finish-unknown"].includes(record.phase)
+      || ![identity.accountUserId, identity.authUserId].includes(record.serverAccountUserId)) throw controlFailure("No completed or possibly completed dedicated registration can be verified. Inspect its saved phase before creating another.", "REMOTE_ENROLLMENT_PENDING");
+    const enrollment = { ...record.key, clientId: record.clientId, accountUserId: record.serverAccountUserId, ...keySelection(record) };
+    await key("inspect", { enrollment, home, identity });
+    const auth = await context.current();
+    const socket = await open({ ...auth, enrollment, environmentId: "env_registration_probe", sign: async challenge => {
+      await context.current(); return dedicatedConnectionProof(enrollment, challenge, { home, identity });
+    } });
+    // Authentication only: do not initialize a stream, open a task or send RPC.
+    socket.terminate();
+    record.phase = "enrolled"; await saveDevice(home, identity, record);
+    const hosts = [], seen = new Set(); let cursor;
+    for (let page = 0; page < 100; page++) {
+      const route = `/codex/remote/control/clients/${encodeURIComponent(enrollment.clientId)}/environments?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
+      const response = await context.request(route, { method: "GET" });
+      if (!Array.isArray(response?.items) || response.items.some(item => !/^env_[A-Za-z0-9_-]+$/.test(item?.env_id ?? ""))) throw controlFailure("Invalid paired-host list.", "REMOTE_PAIR_UNKNOWN");
+      hosts.push(...response.items.map(item => `remote-control:${item.env_id}`));
+      if (response.cursor == null) {
+        record.pairings = [...new Set(hosts)].map(host_id => ({ host_id, verified_at: new Date().toISOString() }));
+        record.pairing_unknown = false; await saveDevice(home, identity, record); return deviceStatus(record);
+      }
+      if (typeof response.cursor !== "string" || !response.cursor || seen.has(response.cursor) || response.cursor.length > 4096) throw controlFailure("Invalid paired-host pagination.", "REMOTE_PAIR_UNKNOWN");
+      seen.add(response.cursor); cursor = response.cursor;
+    }
+    throw controlFailure("Paired-host history exceeded its limit.", "REMOTE_PAIR_UNKNOWN");
+  });
+}

package/src/remote-io.mjs

@@ -0,0 +1,163 @@
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { withRemoteClient, requirePairedManagement } from "./remote-management.mjs";
+import { remoteControlConnection } from "./remote-control.mjs";
+import { hostFields } from "./target.mjs";
+import { fetchThread } from "./observe.mjs";
+import { setTimeout as delay } from "node:timers/promises";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { withSupervisedMutation } from "./supervision.mjs";
+
+const fail = (message, code = "REMOTE_FILESYSTEM_ERROR") => Object.assign(new Error(message), { code });
+export const remotePathApi = value => /^[A-Za-z]:[\\/]|^\\\\/.test(value) ? path.win32 : path.posix;
+export const resolveRemotePath = (cwd, value) => remotePathApi(cwd).resolve(cwd, value);
+const within = (file, root) => { const relative = remotePathApi(root).relative(root, file); return relative === "" || (!relative.startsWith("..") && !remotePathApi(root).isAbsolute(relative)); };
+const excluded = (file, excludes) => file.split(/[\\/]/).includes(".git") || excludes.some(root => within(file, root));
+const hash = value => createHash("sha256").update(value).digest("hex");
+
+async function metadata(client, file) {
+  const value = await client.request("fs/getMetadata", { path: file });
+  if (typeof value?.isFile !== "boolean" || typeof value.isDirectory !== "boolean" || typeof value.isSymlink !== "boolean" || !Number.isFinite(value.modifiedAtMs)) throw fail("Invalid remote file metadata.");
+  if (value.isSymlink) throw fail("Remote symlinks cannot be fingerprinted without a canonical target API.", "REMOTE_SYMLINK_UNSUPPORTED");
+  return value;
+}
+
+export async function remoteFingerprintFile(file, client) {
+  requirePairedManagement();
+  if (!remotePathApi(file).isAbsolute(file)) throw fail("Remote evidence requires an absolute path.");
+  if (!client) return withRemoteClient(c => remoteFingerprintFile(file, c));
+  const before = await metadata(client, file);
+  if (!before.isFile) throw fail("Remote evidence must be a regular file.");
+  const response = await client.request("fs/readFile", { path: file });
+  if (typeof response?.dataBase64 !== "string" || response.dataBase64.length > 48 * 1024 * 1024 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(response.dataBase64)) throw fail("Remote evidence is invalid or exceeds its size limit.");
+  const bytes = Buffer.from(response.dataBase64, "base64"), after = await metadata(client, file);
+  if (JSON.stringify(before) !== JSON.stringify(after)) throw fail("Remote evidence changed while reading.", "STALE_EVIDENCE");
+  return { type: "file", ref: file, path: file, size: bytes.length, sha256: hash(bytes), mtime_ms: after.modifiedAtMs, ctime_ms: after.createdAtMs, ...hostFields() };
+}
+
+export async function remoteCaptureInputs(roots, excludes = [], { allowMissing = false, client } = {}) {
+  if (!client) return withRemoteClient(c => remoteCaptureInputs(roots, excludes, { allowMissing, client: c }));
+  const records = new Map();
+  const visit = async file => {
+    if (excluded(file, excludes) || records.has(file)) return;
+    if (records.size >= 10000) throw fail("Remote checkpoint exceeds 10000 entries.");
+    let info;
+    try { info = await metadata(client, file); } catch (error) {
+      // Generic RPC rejection is not proof of ENOENT. Preserve uncertainty.
+      if (allowMissing && error.code === "ENOENT") return; throw error;
+    }
+    if (info.isDirectory) {
+      records.set(file, { type: "directory", ref: file });
+      const result = await client.request("fs/readDirectory", { path: file });
+      if (!Array.isArray(result?.entries) || result.entries.some(e => typeof e.fileName !== "string" || !e.fileName || /^[.]{1,2}$/.test(e.fileName) || /[\\/\0]/.test(e.fileName))) throw fail("Invalid remote directory entries.");
+      for (const entry of result.entries.sort((a, b) => a.fileName.localeCompare(b.fileName))) await visit(remotePathApi(file).join(file, entry.fileName));
+    } else if (info.isFile) records.set(file, await remoteFingerprintFile(file, client));
+    else throw fail("Remote snapshots require regular files or directories.");
+  };
+  for (const root of roots) await visit(root);
+  const files = [...records.values()].sort((a, b) => a.ref.localeCompare(b.ref));
+  return { roots, excludes, files, digest: hash(JSON.stringify(files)) };
+}
+
+export async function remoteCheckpointScope(threadId, paths, excludes = []) {
+  return withRemoteClient(async client => {
+    const thread = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
+    if (thread?.id !== threadId || typeof thread.cwd !== "string" || !remotePathApi(thread.cwd).isAbsolute(thread.cwd)) throw fail("Remote checkpoint task scope is unavailable.");
+    return { cwd: thread.cwd, roots: [...new Set(paths.map(p => resolveRemotePath(thread.cwd, p)))], excludes: excludes.map(p => resolveRemotePath(thread.cwd, p)) };
+  });
+}
+
+export async function remoteWatchInputs(snapshot, { route: makeRoute = remoteControlConnection } = {}) {
+  requirePairedManagement(); const route = makeRoute(), runtime = await route.discover(), client = await route.connect(runtime.paths.socket);
+  const touched = new Set(), ids = new Set(); let error = null;
+  const notification = event => {
+    if (event.method !== "fs/changed" || !ids.has(event.params?.watchId)) return;
+    if (!Array.isArray(event.params.changedPaths)) { error = "Invalid remote watch event."; return; }
+    for (const file of event.params.changedPaths) if (typeof file !== "string") error = "Invalid remote watch path.";
+    else if (!excluded(file, snapshot.excludes) && snapshot.roots.some(root => within(file, root)) && touched.size < 100) touched.add(file);
+  };
+  client.on("notification", notification);
+  try {
+    for (const root of snapshot.roots) { const watchId = randomUUID(); ids.add(watchId); const result = await client.request("fs/watch", { path: root, watchId }); if (typeof result?.path !== "string") throw fail("Remote filesystem watch was not acknowledged."); }
+    return { touched, get error() { return error ?? (client.isOpen() ? null : "Remote filesystem watch disconnected."); }, async close() {
+      try { for (const watchId of ids) await client.request("fs/unwatch", { watchId }).catch(() => {}); } finally { client.off("notification", notification); client.close(); }
+    } };
+  } catch (error) { client.close(); throw error; }
+}
+
+export async function runRemoteCommand(argv, { cwd, timeoutMs = 0, signal, onStart = async () => {} } = {}, dependencies = {}) {
+  requirePairedManagement(); const processId = randomUUID(), started = new Date().toISOString(), timeout = timeoutMs || 86400000;
+  return withRemoteClient(async client => {
+    if (signal?.aborted) throw fail("Remote command cancelled before dispatch.", "CANCELLED");
+    // processId is connection scoped and only this invocation can terminate it.
+    let cancelError = null;
+    const cancel = () => { client.request("command/exec/terminate", { processId }, { mutation: true }).catch(error => { cancelError = error; }); };
+    signal?.addEventListener("abort", cancel, { once: true });
+    try {
+      await onStart(null, { remote_process_id: processId, execution_backend: "app-server" });
+      const result = await client.request("command/exec", { command: argv, ...(cwd ? { cwd } : {}), timeoutMs: timeout, outputBytesCap: 32768, processId }, { mutation: true });
+      if (!Number.isInteger(result?.exitCode) || typeof result.stdout !== "string" || typeof result.stderr !== "string") throw Object.assign(fail("Remote command acknowledgement was invalid.", "REMOTE_COMMAND_UNKNOWN"), { uncertain: true });
+      return { pid: null, remote_process_id: processId, ...hostFields(), exit_code: result.exitCode, signal: null, timed_out: false, started_at: started,
+        completed_at: new Date().toISOString(), output_tail: (result.stdout + result.stderr).slice(-32768), output_truncated: result.stdout.length + result.stderr.length >= 32768,
+        error: cancelError ? "Remote cancellation was not acknowledged." : signal?.aborted ? "Remote command interrupted." : null };
+    } catch (error) { error.remote_process_id = processId; throw error; }
+    finally { signal?.removeEventListener("abort", cancel); }
+  }, { ...dependencies, timeoutMs: timeout + 10000 });
+}
+
+export function remoteShellScript(argv, { cwd, shell, marker }) {
+  if (!["powershell", "posix"].includes(shell) || !/^[a-f0-9-]{36}$/.test(marker) || argv.some(arg => typeof arg !== "string" || arg.includes("\0"))) throw fail("An explicit powershell or posix --shell and valid argv are required.", "REMOTE_SHELL_REQUIRED");
+  const tag = `CODEXTEER_EXEC_${marker}`;
+  if (shell === "powershell") {
+    const q = value => `'${value.replaceAll("'", "''")}'`;
+    return `$ErrorActionPreference='Stop'; $codexteerStatus=1; try { ${cwd ? `Set-Location -LiteralPath ${q(cwd)}; ` : ""}& ${argv.map(q).join(" ")}; $codexteerStatus=if ($null -eq $LASTEXITCODE) {0} else {$LASTEXITCODE} } catch { Write-Output $_.Exception.Message }; Write-Output ("\u0060n${tag}:" + $codexteerStatus); exit $codexteerStatus`;
+  }
+  const q = value => `'${value.replaceAll("'", "'\\''")}'`;
+  return `{ ${cwd ? `cd -- ${q(cwd)} && ` : ""}${argv.map(q).join(" ")}; }; codexteer_status=$?; printf '\\n${tag}:%s\\n' "$codexteer_status"; exit "$codexteer_status"`;
+}
+
+// This is an explicitly selected, task-scoped host shell (the official API is
+// unsandboxed). Never use it as fallback for a refused command/exec request.
+export async function runRemoteShellCommand(argv, { cwd, threadId, shell, timeoutMs = 0, signal, onStart = async () => {}, supervisor, connection } = {}, dependencies = {}) {
+  requirePairedManagement();
+  if (!threadId) throw fail("thread-shell requires --thread (checkpoint uses its own task).", "REMOTE_SHELL_REQUIRED");
+  threadId = normalizeThreadId(threadId);
+  const marker = randomUUID(), command = remoteShellScript(argv, { cwd, shell, marker }), tag = `CODEXTEER_EXEC_${marker}`, started = new Date().toISOString(), timeout = timeoutMs || 3600000;
+  return withRemoteClient(async (client, runtime) => {
+    const thread = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
+    if (thread?.id !== threadId || !["idle", "notLoaded"].includes(thread.status?.type)) throw fail("Explicit thread-shell execution requires the selected task to be idle.", "REMOTE_SHELL_TASK_BUSY");
+    if (signal?.aborted) throw fail("Remote shell cancelled before dispatch.", "CANCELLED");
+    let accepted = false;
+    try {
+      await onStart(null, { remote_process_id: marker, execution_backend: "thread-shell", remote_shell: shell });
+      // Recheck after every preparation await. Pause/stop shares this lock,
+      // so it cannot acknowledge between this check and dispatch acceptance.
+      // Release after the RPC receipt; an accepted command is not cancellable
+      // through supervisor control and can still be observed while paused.
+      const acknowledgement = await withSupervisedMutation(threadId, supervisor, () => {
+        if (signal?.aborted) throw fail("Remote shell cancelled before dispatch.", "CANCELLED");
+        return client.request("thread/shellCommand", { threadId, command, timeoutMs: timeout }, { mutation: true });
+      }, { connection, home: runtime.paths.home }); accepted = true;
+      if (!acknowledgement || typeof acknowledgement !== "object" || Array.isArray(acknowledgement)) throw fail("Remote shell acknowledgement was invalid. Inspect the same command before retrying.", "REMOTE_COMMAND_UNKNOWN");
+      const deadline = Date.now() + timeout + 10000;
+      do {
+        if (signal?.aborted) throw fail("Remote shell observation interrupted; the host command may still run until its timeout.", "REMOTE_COMMAND_UNKNOWN");
+        const history = await fetchThread(client, threadId);
+        const matches = history.turns.flatMap(turn => turn.items ?? []).filter(item => item.type === "commandExecution" && item.command?.includes(tag));
+        if (matches.length > 1) throw fail("Remote command identity was not unique.", "REMOTE_COMMAND_UNKNOWN");
+        const item = matches[0];
+        if (item && ["completed", "failed"].includes(item.status) && Number.isInteger(item.exitCode)) {
+          const output = item.aggregatedOutput ?? "", markerLine = new RegExp(`^${tag}:(-?\\d+)\\r?$`, "gm"), markers = [...output.matchAll(markerLine)];
+          if (markers.length !== 1 || Number(markers[0][1]) !== item.exitCode) throw fail("Remote shell exit status could not be correlated with its completion marker.", "REMOTE_COMMAND_UNKNOWN");
+          // App Server aggregates stdout and stderr; stderr may follow the
+          // stdout marker even though the command has already completed.
+          const clean = output.replace(new RegExp(`^${tag}:-?\\d+\\r?\\n?`, "m"), "");
+          return { pid: null, remote_process_id: marker, thread_id: threadId, execution_backend: "thread-shell", execution_permissions: "host-full-access", ...hostFields(),
+            exit_code: item.exitCode, signal: null, timed_out: false, started_at: started, completed_at: new Date().toISOString(), output_tail: clean.slice(-32768), output_truncated: clean.length > 32768, error: null };
+        }
+        if (Date.now() >= deadline) break; await delay(250);
+      } while (true);
+      throw fail("Remote shell completion was not observed. Do not replay the command.", "REMOTE_COMMAND_UNKNOWN");
+    } catch (error) { error.remote_process_id = marker; if (accepted) error.uncertain = true; throw error; }
+  }, dependencies);
+}

package/src/remote-key-access.mjs

@@ -0,0 +1,76 @@
+import { open } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { BUNDLED_NODE } from "./wrapper.mjs";
+
+const DESKTOP = "/Applications/ChatGPT.app/Contents/MacOS/ChatGPT";
+
+// Read public code-signature metadata only. Do not load Desktop code, attach to
+// its process, alter entitlements, or query/export Keychain item material.
+export function entitlementBlob(signature) {
+  if (signature.length < 12 || signature.readUInt32BE(0) !== 0xfade0cc0) throw new Error("Invalid signature container");
+  const length = signature.readUInt32BE(4), count = signature.readUInt32BE(8);
+  // LC_CODE_SIGNATURE reserves aligned zero-filled capacity beyond the actual
+  // SuperBlob. Only that padding may lie outside its declared length.
+  if (length < 12 || length > signature.length || signature.subarray(length).some(byte => byte !== 0)
+    || count > 1024 || 12 + count * 8 > length) throw new Error("Invalid signature index");
+  for (let index = 0; index < count; index++) {
+    const slot = 12 + index * 8, offset = signature.readUInt32BE(slot + 4);
+    if (signature.readUInt32BE(slot) !== 5) continue;
+    if (offset < 12 + count * 8 || offset + 8 > length || signature.readUInt32BE(offset) !== 0xfade7171) throw new Error("Invalid entitlement slot");
+    const size = signature.readUInt32BE(offset + 4);
+    if (size < 8 || offset + size > length) throw new Error("Invalid entitlement size");
+    return signature.subarray(offset + 8, offset + size);
+  }
+  return null;
+}
+
+async function embeddedEntitlements(executable) {
+  const file = await open(executable, "r");
+  try {
+    const exact = async (length, offset) => {
+      const bytes = Buffer.alloc(length);
+      if ((await file.read(bytes, 0, length, offset)).bytesRead !== length) throw new Error("Incomplete signature metadata");
+      return bytes;
+    };
+    const header = await exact(32, 0);
+    // The installed Desktop and bundled Node use little-endian thin Mach-O64.
+    // Unknown layouts are reported as unverified, never treated as authorized.
+    if (header.readUInt32LE(0) !== 0xfeedfacf) throw new Error("Unrecognized executable layout");
+    const count = header.readUInt32LE(16), size = header.readUInt32LE(20);
+    if (count > 4096 || size > 1024 * 1024) throw new Error("Invalid load commands");
+    const commands = await exact(size, 32);
+    for (let index = 0, offset = 0; index < count; index++) {
+      if (offset + 8 > size) throw new Error("Incomplete load command");
+      const command = commands.readUInt32LE(offset), length = commands.readUInt32LE(offset + 4);
+      if (length < 8 || offset + length > size) throw new Error("Invalid load command");
+      if (command === 0x1d) {
+        if (length < 16) throw new Error("Invalid code signature command");
+        const start = commands.readUInt32LE(offset + 8), bytes = commands.readUInt32LE(offset + 12);
+        if (bytes > 16 * 1024 * 1024) throw new Error("Signature metadata too large");
+        return entitlementBlob(await exact(bytes, start));
+      }
+      offset += length;
+    }
+    throw new Error("No code signature metadata");
+  } finally { await file.close(); }
+}
+
+export async function inspectKeychainIdentities({ read = embeddedEntitlements, run = spawnSync } = {}) {
+  const summary = async executable => {
+    try {
+      const xml = await read(executable);
+      if (!xml) throw new Error();
+      const result = run("/usr/bin/plutil", ["-convert", "json", "-o", "-", "--", "-"], { input: xml, encoding: "utf8", timeout: 3000, maxBuffer: 1024 * 1024 });
+      if (result.status !== 0) throw new Error();
+      const values = JSON.parse(result.stdout), groups = values["keychain-access-groups"];
+      if (groups !== undefined && (!Array.isArray(groups) || groups.some(value => typeof value !== "string"))) throw new Error();
+      return { status: "observed", application_identifier: typeof (values["com.apple.application-identifier"] ?? values["application-identifier"]) === "string",
+        keychain_access_group_count: groups?.length ?? 0 };
+    } catch { return { status: "unverified" }; }
+  };
+  const [desktop, helper] = await Promise.all([summary(DESKTOP), summary(BUNDLED_NODE)]);
+  return { source: "embedded-public-entitlements", desktop, helper,
+    different_keychain_identity: desktop.status !== "observed" || helper.status !== "observed" ? null
+      : desktop.application_identifier !== helper.application_identifier || desktop.keychain_access_group_count !== helper.keychain_access_group_count,
+    interpretation: "Identity metadata can explain access differences; it does not prove the enrolled key is missing from Desktop." };
+}

package/src/remote-key-worker.mjs

@@ -0,0 +1,38 @@
+import { readFile, lstat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { readEnrollment, enrollmentHash, connectionPayload, verifyDeviceProof } from "./remote-control-auth.mjs";
+
+// No generic signing interface, key creation, enrollment or network access.
+let stage = "input";
+try {
+  const file = process.argv[2], info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077) || info.size > 16384) throw new Error();
+  const input = JSON.parse(await readFile(file, "utf8")); stage = "enrollment";
+  if (!["inspect", "sign"].includes(input.operation) || (input.operation === "inspect" && input.challenge !== undefined)) throw new Error();
+  const enrollment = await readEnrollment(input.home, input.identity);
+  if (enrollmentHash(enrollment) !== input.enrollmentHash) throw new Error();
+  const payload = input.operation === "sign" ? Buffer.from(JSON.stringify({ domain: "codex-device-key-sign-payload/v1", payload: connectionPayload(input.challenge, enrollment) })) : null;
+  stage = "addon";
+  const native = createRequire(import.meta.url)("/Applications/ChatGPT.app/Contents/Resources/native/remote-control-device-key.node");
+  stage = "public-key";
+  const key = await native.getDeviceKeyPublic(enrollment.keyId);
+  stage = "public-key-match";
+  for (const field of ["keyId", "algorithm", "protectionClass", "publicKeySpkiDerBase64"]) if (key[field] !== enrollment[field]) throw new Error();
+  if (input.operation === "inspect") {
+    process.stdout.write(JSON.stringify({ ok: true, operation: "inspect", device_key_access: "verified" }));
+  } else {
+    stage = "sign";
+    const signature = await native.signDeviceKey(enrollment.keyId, payload);
+    stage = "verify";
+    const proof = verifyDeviceProof({ type: "device_key_proof", keyId: enrollment.keyId, algorithm: signature.algorithm,
+      signatureDerBase64: signature.signatureDerBase64, signedPayloadBase64: payload.toString("base64") }, input.challenge, enrollment);
+    process.stdout.write(JSON.stringify({ ok: true, proof }));
+  }
+} catch (error) {
+  const status = error?.message?.match(/(?:OSStatus|status|Security\.framework error code)[^\d-]*(-?\d+)/i)?.[1];
+  const known = { "No keychain is available. You may need to restart your computer.": "KEYCHAIN_UNAVAILABLE",
+    "device key not found": "DEVICE_KEY_NOT_FOUND", "invalid device key id": "DEVICE_KEY_ID_INVALID",
+    remote_control_device_key_unusable: "DEVICE_KEY_UNUSABLE", remote_control_device_key_store_unavailable: "DEVICE_KEY_STORE_UNAVAILABLE" };
+  const nativeCode = known[error?.message] ?? known[error?.errorCode] ?? (typeof error?.code === "number" || /^[A-Z][A-Z0-9_:-]{0,79}$/.test(error?.code ?? "") ? error.code : status ? Number(status) : null);
+  process.stdout.write(JSON.stringify({ ok: false, code: "REMOTE_AUTH_SIGNING_FAILED", stage, native_code: nativeCode })); process.exitCode = 1;
+}

package/src/remote-keychain.mjs

@@ -0,0 +1,72 @@
+import { readFile, lstat, mkdir, writeFile, rename, rm, chmod } from "node:fs/promises";
+import { createHash, randomUUID, verify } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { deviceStore, validateDeviceKey } from "./remote-device-store.mjs";
+import { connectionPayload, controlFailure } from "./remote-control-auth.mjs";
+import { enrollmentPayload } from "./remote-device-protocol.mjs";
+
+const execute = promisify(execFile), hash = bytes => createHash("sha256").update(bytes).digest("hex");
+async function owned(file, directory = false) {
+  const info = await lstat(file);
+  if (info.uid !== process.getuid() || info.isSymbolicLink() || (info.mode & 0o077) || !(directory ? info.isDirectory() : info.isFile())) throw controlFailure("Unsafe dedicated key helper runtime.", "REMOTE_DEVICE_STORE_UNSAFE");
+}
+
+export async function prepareKeychainRuntime(home, identity) {
+  const { file } = await deviceStore(home, identity, { create: true }), root = path.join(path.dirname(file), "key-helpers");
+  await mkdir(root, { mode: 0o700 }).catch(error => { if (error.code !== "EEXIST") throw error; }); await owned(root, true);
+  const source = await readFile(new URL("../assets/remote-device-key.swift", import.meta.url)), sourceHash = hash(Buffer.concat([source, Buffer.from(process.arch)]));
+  const directory = path.join(root, sourceHash), binary = path.join(directory, "device-key");
+  try { await owned(directory, true); await owned(path.join(directory, "manifest.json")); const manifest = JSON.parse(await readFile(path.join(directory, "manifest.json"), "utf8"));
+    const runtime = { source: sourceHash, sha256: manifest.sha256 }; await keychainBinary(home, identity, runtime); return runtime;
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+  const staging = path.join(root, `.build-${randomUUID()}`); await mkdir(staging, { mode: 0o700 });
+  try {
+    const swift = path.join(staging, "device-key.swift"), target = path.join(staging, "device-key"); await writeFile(swift, source, { mode: 0o600 });
+    try {
+      await execute("/usr/bin/xcrun", ["swiftc", swift, "-O", "-framework", "Security", "-framework", "Foundation", "-module-cache-path", path.join(staging, "module-cache"), "-o", target], { timeout: 120000, maxBuffer: 65536 });
+      await chmod(target, 0o700);
+      // Ad-hoc sign our own new helper only. No Desktop binary or privileged
+      // entitlement is modified; no user's signing certificate is accessed.
+      await execute("/usr/bin/codesign", ["--sign", "-", "--identifier", "dev.codexteer.device-key", target], { timeout: 10000, maxBuffer: 16384 });
+    } catch { throw controlFailure("Cannot build the dedicated Keychain helper. Xcode command-line tools are required; no key was created.", "REMOTE_KEY_HELPER_BUILD_FAILED"); }
+    const runtime = { source: sourceHash, sha256: hash(await readFile(target)) };
+    await writeFile(path.join(staging, "manifest.json"), JSON.stringify(runtime), { mode: 0o600 });
+    await rm(path.join(staging, "module-cache"), { recursive: true, force: true }); await rm(swift);
+    await rename(staging, directory); return runtime;
+  } finally { await rm(staging, { recursive: true, force: true }); }
+}
+
+async function keychainBinary(home, identity, runtime) {
+  if (!/^[a-f0-9]{64}$/.test(runtime?.source ?? "") || !/^[a-f0-9]{64}$/.test(runtime?.sha256 ?? "")) throw controlFailure("Invalid pinned key helper.", "REMOTE_DEVICE_STORE_UNSAFE");
+  const { file } = await deviceStore(home, identity), root = path.join(path.dirname(file), "key-helpers"), directory = path.join(root, runtime.source), binary = path.join(directory, "device-key");
+  await owned(root, true); await owned(directory, true); await owned(binary);
+  if (hash(await readFile(binary)) !== runtime.sha256) throw controlFailure("Pinned key helper changed. No signing was attempted.", "REMOTE_DEVICE_STORE_UNSAFE");
+  await execute("/usr/bin/codesign", ["--verify", "--strict", binary], { timeout: 10000, maxBuffer: 16384 }); return binary;
+}
+
+export async function keychainOperation(operation, input) {
+  const { home, identity, runtime } = input, binary = await keychainBinary(home, identity, runtime);
+  const { file: record } = await deviceStore(home, identity), request = path.join(path.dirname(record), `.request-${randomUUID()}.json`);
+  let payload;
+  if (operation === "connection-proof") payload = connectionPayload(input.challenge, input.enrollment);
+  else if (operation === "enrollment-proof") payload = enrollmentPayload(input.challenge, input.enrollment, input.path);
+  const bytes = payload ? Buffer.from(JSON.stringify({ domain: "codex-device-key-sign-payload/v1", payload })) : null;
+  try {
+    await writeFile(request, JSON.stringify({ operation: operation === "create" ? "create" : ["inspect", "recover"].includes(operation) ? "inspect" : "sign",
+      keyId: input.enrollment?.keyId ?? input.keyId, ...(bytes ? { signedPayloadBase64: bytes.toString("base64") } : {}) }), { mode: 0o600, flag: "wx" });
+    let response;
+    try { response = JSON.parse((await execute(binary, [request], { timeout: 10000, maxBuffer: 32768 })).stdout); }
+    catch { throw controlFailure("Dedicated Keychain helper lost its acknowledgement. Inspect the saved phase before retrying.", "REMOTE_DEDICATED_KEY_UNAVAILABLE"); }
+    if (response.ok !== true) throw controlFailure(`Dedicated Keychain operation failed at ${["input", "create", "validate", "public-key", "payload", "sign"].includes(response.stage) ? response.stage : "worker"} (${Number.isSafeInteger(response.os_status) ? response.os_status : "UNVERIFIED"}).`, "REMOTE_DEDICATED_KEY_UNAVAILABLE");
+    const key = validateDeviceKey(response.key);
+    if (["create", "recover"].includes(operation)) return key;
+    for (const field of Object.keys(key)) if (key[field] !== input.enrollment[field]) throw controlFailure("Dedicated Keychain public key changed.", "REMOTE_DEVICE_KEY_INVALID");
+    if (operation === "inspect") return;
+    if (!verify("sha256", bytes, { key: Buffer.from(key.publicKeySpkiDerBase64, "base64"), type: "spki", format: "der" }, Buffer.from(response.signatureDerBase64, "base64"))) throw controlFailure("Dedicated signature did not match the enrolled key.", "REMOTE_AUTH_PROOF_INVALID");
+    return operation === "connection-proof" ? { type: "device_key_proof", keyId: key.keyId, algorithm: key.algorithm, signatureDerBase64: response.signatureDerBase64, signedPayloadBase64: bytes.toString("base64") }
+      : { challenge_token: input.challenge.challenge_token, key_id: key.keyId, algorithm: key.algorithm, signature_der_base64: response.signatureDerBase64, signed_payload_base64: bytes.toString("base64") };
+  } finally { await rm(request, { force: true }); }
+}