@makerbi/remodex 1.3.9 → 1.4.0

package/bin/remodex.js

@@ -58,6 +58,7 @@ async function main({
 
   if (command === "up") {
     if (platform === "darwin") {
+      consoleImpl.log("[remodex] Starting bridge and pairing QR...");
       const result = await deps.startMacOSBridgeService({
         waitForPairing: true,
       });

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@makerbi/remodex",
-  "version": "1.3.9",
+  "version": "1.4.0",
   "description": "Local bridge between Codex and the Remodex mobile app. Run `remodex up` to start.",
   "main": "src/index.js",
   "bin": {
-    "remodex": "./bin/remodex.js"
+    "remodex": "bin/remodex.js"
   },
   "files": [
     "bin/",
@@ -24,7 +24,7 @@
     "cli"
   ],
   "author": "Emanuele Di Pietro",
-  "license": "ISC",
+  "license": "Apache-2.0",
   "type": "commonjs",
   "dependencies": {
     "qrcode-terminal": "^0.12.0",

package/src/bridge.js

@@ -40,6 +40,10 @@ const {
 } = require("./secure-device-state");
 const { createBridgeSecureTransport } = require("./secure-transport");
 const { createRolloutLiveMirrorController } = require("./rollout-live-mirror");
+const {
+  createDesktopIpcActionFollower,
+  seedConversationStateFromThreadRead,
+} = require("./desktop-ipc-action-follower");
 const { version: bridgePackageVersion = "" } = require("../package.json");
 const {
   MINIMUM_SUPPORTED_IOS_APP_VERSION,
@@ -55,6 +59,9 @@ const RELAY_WATCHDOG_PING_INTERVAL_MS = 10_000;
 const RELAY_WATCHDOG_STALE_AFTER_MS = 70_000;
 const BRIDGE_STATUS_HEARTBEAT_INTERVAL_MS = 5_000;
 const STALE_RELAY_STATUS_MESSAGE = "Relay heartbeat stalled; reconnect pending.";
+const CLOSE_CODE_INVALID_RELAY_REQUEST = 4000;
+const CLOSE_CODE_REPLACED_BY_NEW_MAC = 4001;
+const CLOSE_CODE_MAC_UNAUTHORIZED = 4005;
 const RELAY_HISTORY_IMAGE_REFERENCE_URL = "remodex://history-image-elided";
 const RELAY_THREAD_PAYLOAD_SOFT_LIMIT_BYTES = 4 * 1024 * 1024;
 const RELAY_HISTORY_TEXT_TAIL_LIMIT_CHARS = 24_000;
@@ -146,6 +153,7 @@ function startBridge({
   let lastRelayActivityAt = 0;
   let lastPublishedBridgeStatus = null;
   let lastConnectionStatus = null;
+  let lastConnectionError = "";
   let codexLaunchState = config.codexEndpoint ? "connected" : "starting";
   let codexHandshakeState = config.codexEndpoint ? "warm" : "cold";
   const forwardedInitializeRequestIds = new Set();
@@ -194,6 +202,13 @@ function startBridge({
       sendApplicationResponse,
     })
     : null;
+  const desktopIpcActionFollower = !config.codexEndpoint
+    ? createDesktopIpcActionFollower({
+      sendApplicationResponse,
+      readConversationState: readDesktopConversationState,
+      socketPath: config.desktopIpcSocketPath || undefined,
+    })
+    : null;
   let contextUsageWatcher = null;
   let watchedContextUsageKey = null;
 
@@ -322,35 +337,42 @@ function startBridge({
   }
 
   // Keeps npm start output compact by emitting only high-signal connection states.
-  function logConnectionStatus(status) {
-    if (lastConnectionStatus === status) {
+  function logConnectionStatus(status, lastError = "") {
+    if (lastConnectionStatus === status && lastConnectionError === lastError) {
       return;
     }
 
     lastConnectionStatus = status;
+    lastConnectionError = lastError;
     publishBridgeStatus({
       state: "running",
       connectionStatus: status,
       pid: process.pid,
-      lastError: "",
+      lastError,
     });
     console.log(`[remodex] ${status}`);
+    if (lastError) {
+      console.error(`[remodex] ${lastError}`);
+    }
   }
 
   // Retries the relay socket while preserving the active Codex process and session id.
-  function scheduleRelayReconnect(closeCode) {
+  function scheduleRelayReconnect(closeCode, closeReason = "") {
     if (isShuttingDown) {
       return;
     }
 
-    if (closeCode === 4000 || closeCode === 4001) {
-      logConnectionStatus("disconnected");
+    if (isTerminalRelayCloseCode(closeCode)) {
+      const lastError = buildRelayCloseStatusError(closeCode, closeReason);
+      logConnectionStatus("disconnected", lastError);
       shutdown(codex, () => socket, () => {
         isShuttingDown = true;
         bridgeWakeAssertion.stop();
         clearReconnectTimer();
         clearRelayWatchdog();
         clearBridgeStatusHeartbeat();
+      }, {
+        exitCode: closeCode === CLOSE_CODE_MAC_UNAUTHORIZED ? 1 : 0,
       });
       return;
     }
@@ -421,18 +443,20 @@ function startBridge({
       markRelayActivity();
     });
 
-    nextSocket.on("close", (code) => {
+    nextSocket.on("close", (code, reason) => {
+      const closeReason = normalizeWebSocketCloseReason(reason);
       if (socket === nextSocket) {
         clearRelayWatchdog();
       }
-      logConnectionStatus("disconnected");
+      logConnectionStatus("disconnected", buildRelayCloseStatusError(code, closeReason));
       if (socket === nextSocket) {
         socket = null;
       }
       stopContextUsageWatcher();
       rolloutLiveMirror?.stopAll();
+      desktopIpcActionFollower?.stopAll();
       desktopRefresher.handleTransportReset();
-      scheduleRelayReconnect(code);
+      scheduleRelayReconnect(code, closeReason);
     });
 
     nextSocket.on("error", () => {
@@ -473,18 +497,20 @@ function startBridge({
   codex.onClose(() => {
     clearRelayWatchdog();
     clearBridgeStatusHeartbeat();
-    logConnectionStatus("disconnected");
+    const lastError = lastConnectionError || "";
+    logConnectionStatus("disconnected", lastError);
     publishBridgeStatus({
       state: "stopped",
       connectionStatus: "disconnected",
       pid: process.pid,
-      lastError: "",
+      lastError,
     });
     isShuttingDown = true;
     bridgeWakeAssertion.stop();
     clearReconnectTimer();
     stopContextUsageWatcher();
     rolloutLiveMirror?.stopAll();
+    desktopIpcActionFollower?.stopAll();
     desktopRefresher.handleTransportReset();
     failBridgeManagedCodexRequests(new Error("Codex transport closed before the bridge request completed."));
     forwardedRequestMethodsById.clear();
@@ -547,6 +573,9 @@ function startBridge({
     }
     desktopRefresher.handleInbound(rawMessage);
     rolloutLiveMirror?.observeInbound(rawMessage);
+    if (desktopIpcActionFollower?.observeInbound(rawMessage)) {
+      return;
+    }
     rememberForwardedRequestMethod(rawMessage);
     rememberThreadFromMessage("phone", rawMessage);
     codex.send(rawMessage);
@@ -579,6 +608,15 @@ function startBridge({
     }));
   }
 
+  // Seeds the desktop IPC follower when it receives patches before a full snapshot.
+  async function readDesktopConversationState(threadId) {
+    const result = await sendCodexRequest("thread/read", {
+      threadId,
+      includeTurns: true,
+    });
+    return seedConversationStateFromThreadRead(result);
+  }
+
   // ─── Bridge-owned auth snapshot ─────────────────────────────
 
   // Handles the bridge-owned auth status wrappers without exposing tokens to the phone.
@@ -1281,7 +1319,7 @@ function buildMacRegistration(deviceState, pairingSession) {
   };
 }
 
-function shutdown(codex, getSocket, beforeExit = () => {}) {
+function shutdown(codex, getSocket, beforeExit = () => {}, { exitCode = 0 } = {}) {
   beforeExit();
 
   const socket = getSocket();
@@ -1291,7 +1329,41 @@ function shutdown(codex, getSocket, beforeExit = () => {}) {
 
   codex.shutdown();
 
-  setTimeout(() => process.exit(0), 100);
+  setTimeout(() => process.exit(exitCode), 100);
+}
+
+function isTerminalRelayCloseCode(closeCode) {
+  return closeCode === CLOSE_CODE_INVALID_RELAY_REQUEST
+    || closeCode === CLOSE_CODE_REPLACED_BY_NEW_MAC
+    || closeCode === CLOSE_CODE_MAC_UNAUTHORIZED;
+}
+
+function normalizeWebSocketCloseReason(reason) {
+  if (typeof reason === "string") {
+    return reason.trim();
+  }
+
+  if (Buffer.isBuffer(reason)) {
+    return reason.toString("utf8").trim();
+  }
+
+  return "";
+}
+
+function buildRelayCloseStatusError(closeCode, closeReason = "") {
+  if (!Number.isInteger(closeCode) || closeCode === 1000 || closeCode === 1005) {
+    return "";
+  }
+
+  const normalizedReason = normalizeNonEmptyString(closeReason);
+  if (closeCode === CLOSE_CODE_MAC_UNAUTHORIZED) {
+    return normalizedReason
+      || "Relay authorization failed. Set REMODEX_RELAY_ACCESS_TOKEN or use a relay that does not require a Mac access token.";
+  }
+
+  return normalizedReason
+    ? `Relay closed the connection (${closeCode}): ${normalizedReason}`
+    : `Relay closed the connection (${closeCode}).`;
 }
 
 function extractBridgeMessageContext(rawMessage) {
@@ -2103,10 +2175,12 @@ function persistBridgePreferences(
 
 module.exports = {
   buildHeartbeatBridgeStatus,
+  buildRelayCloseStatusError,
   buildRelayAccessTokenHeaders,
   buildRelayUserAgentHeader,
   createMacOSBridgeWakeAssertion,
   hasRelayConnectionGoneStale,
+  isTerminalRelayCloseCode,
   persistBridgePreferences,
   sanitizeLiveGeneratedImageMessageForRelay,
   sanitizeThreadHistoryImagesForRelay,

package/src/codex-desktop-refresher.js

@@ -587,6 +587,7 @@ function readBridgeConfig({
       ? (persistedKeepMacAwakeEnabled == null ? false : persistedKeepMacAwakeEnabled)
       : explicitKeepMacAwakeEnabled,
     codexEndpoint,
+    desktopIpcSocketPath: readFirstDefinedEnv(["REMODEX_DESKTOP_IPC_SOCKET"], "", env),
     refreshCommand,
     codexBundleId: readFirstDefinedEnv(["REMODEX_CODEX_BUNDLE_ID"], DEFAULT_BUNDLE_ID, env),
     codexAppPath: DEFAULT_APP_PATH,

package/src/desktop-ipc-action-follower.js

@@ -0,0 +1,648 @@
+// FILE: desktop-ipc-action-follower.js
+// Purpose: Mirrors live Codex Desktop IPC pending actions to the phone and routes replies back to the desktop runtime.
+// Layer: CLI helper
+// Exports: createDesktopIpcActionFollower, projectPendingDesktopActions
+// Depends on: net, os, path
+
+const net = require("net");
+const os = require("os");
+const path = require("path");
+
+const FRAME_HEADER_BYTES = 4;
+const MAX_FRAME_BYTES = 256 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 10_000;
+const DESKTOP_RESUME_METHODS = new Set(["thread/read", "thread/resume"]);
+const ACTION_METHODS = new Set([
+  "item/commandExecution/requestApproval",
+  "item/fileChange/requestApproval",
+  "item/fileRead/requestApproval",
+  "item/tool/requestUserInput",
+]);
+const REPLY_METHOD_BY_ACTION_METHOD = new Map([
+  ["item/commandExecution/requestApproval", "thread-follower-command-approval-decision"],
+  ["item/fileChange/requestApproval", "thread-follower-file-approval-decision"],
+  ["item/fileRead/requestApproval", "thread-follower-file-approval-decision"],
+  ["item/tool/requestUserInput", "thread-follower-submit-user-input"],
+]);
+const METHOD_VERSION_BY_NAME = new Map([
+  ["initialize", 1],
+  ["thread-follower-command-approval-decision", 1],
+  ["thread-follower-file-approval-decision", 1],
+  ["thread-follower-submit-user-input", 1],
+]);
+const APPROVAL_DECISIONS = new Set(["accept", "acceptForSession", "decline", "cancel"]);
+
+// Opens the Desktop IPC bus on demand and exposes Mac-owned pending actions as normal app-server requests.
+function createDesktopIpcActionFollower({
+  sendApplicationResponse,
+  readConversationState = null,
+  logPrefix = "[remodex]",
+  socketPath = resolveDefaultIpcSocketPath(),
+  netModule = net,
+  now = () => Date.now(),
+  requestTimeoutMs = REQUEST_TIMEOUT_MS,
+} = {}) {
+  const ipc = createDesktopIpcClient({
+    socketPath,
+    netModule,
+    now,
+    requestTimeoutMs,
+    logPrefix,
+    onEnvelope,
+    onDisconnect,
+  });
+  const rawStatesByThreadId = new Map();
+  const pendingRoutesByRequestId = new Map();
+  const activeThreadIds = new Set();
+  const recoveringThreadIds = new Set();
+  const queuedChangesByThreadId = new Map();
+
+  function observeInbound(rawMessage) {
+    const message = safeParseJSON(rawMessage);
+    const responseRoute = desktopRouteForResponse(message);
+    if (responseRoute) {
+      submitDesktopActionResponse(responseRoute, message);
+      return true;
+    }
+
+    const method = readString(message?.method);
+    if (!DESKTOP_RESUME_METHODS.has(method)) {
+      return false;
+    }
+
+    const threadId = readThreadId(message?.params);
+    if (!threadId) {
+      return false;
+    }
+
+    activeThreadIds.add(threadId);
+    ipc.ensureConnected();
+    recoverThreadBaseline(threadId);
+    return false;
+  }
+
+  function stopAll() {
+    rawStatesByThreadId.clear();
+    pendingRoutesByRequestId.clear();
+    activeThreadIds.clear();
+    recoveringThreadIds.clear();
+    queuedChangesByThreadId.clear();
+    ipc.close();
+  }
+
+  // Desktop broadcasts carry the live conversation state Litter projects from.
+  function onEnvelope(envelope) {
+    if (envelope?.type !== "broadcast" || envelope.method !== "thread-stream-state-changed") {
+      return;
+    }
+
+    const params = envelope.params || {};
+    const threadId = readString(params.conversationId) || readString(params.conversation_id);
+    if (!threadId || !activeThreadIds.has(threadId)) {
+      return;
+    }
+
+    if (recoveringThreadIds.has(threadId)) {
+      queueThreadChange(threadId, params.change);
+      return;
+    }
+
+    const previousState = rawStatesByThreadId.get(threadId) || null;
+    const nextState = applyConversationStateChange(previousState, params.change);
+    if (!nextState) {
+      if (isPatchChange(params.change)) {
+        queueThreadChange(threadId, params.change);
+        recoverThreadBaseline(threadId);
+      }
+      return;
+    }
+
+    rawStatesByThreadId.set(threadId, nextState);
+    syncProjectedActions(threadId, projectPendingDesktopActions(threadId, nextState));
+  }
+
+  function onDisconnect() {
+    rawStatesByThreadId.clear();
+    pendingRoutesByRequestId.clear();
+    recoveringThreadIds.clear();
+    queuedChangesByThreadId.clear();
+  }
+
+  function syncProjectedActions(threadId, actions) {
+    const nextRequestIds = new Set(actions.map((action) => action.id));
+    for (const [requestId, route] of Array.from(pendingRoutesByRequestId.entries())) {
+      if (route.threadId !== threadId || nextRequestIds.has(requestId)) {
+        continue;
+      }
+
+      pendingRoutesByRequestId.delete(requestId);
+      sendApplicationResponse(JSON.stringify({
+        method: "serverRequest/resolved",
+        params: {
+          threadId,
+          requestId,
+        },
+      }));
+    }
+
+    for (const action of actions) {
+      if (pendingRoutesByRequestId.has(action.id)) {
+        continue;
+      }
+
+      pendingRoutesByRequestId.set(action.id, {
+        requestId: action.id,
+        method: action.method,
+        threadId,
+      });
+      sendApplicationResponse(JSON.stringify({
+        id: action.id,
+        method: action.method,
+        params: action.params,
+      }));
+    }
+  }
+
+  function desktopRouteForResponse(message) {
+    if (!message || typeof message !== "object" || message.method) {
+      return null;
+    }
+
+    const requestId = requestIdKey(message.id);
+    return requestId ? pendingRoutesByRequestId.get(requestId) || null : null;
+  }
+
+  function submitDesktopActionResponse(route, responseMessage) {
+    const payload = desktopFollowerPayloadForResponse(route, responseMessage);
+    if (!payload) {
+      sendApplicationResponse(JSON.stringify({
+        id: responseMessage?.id ?? route.requestId,
+        error: {
+          code: -32602,
+          message: "Invalid desktop action response.",
+        },
+      }));
+      return;
+    }
+
+    ipc.sendRequest(payload.method, payload.params)
+      .then(() => {
+        pendingRoutesByRequestId.delete(route.requestId);
+        sendApplicationResponse(JSON.stringify({
+          method: "serverRequest/resolved",
+          params: {
+            threadId: route.threadId,
+            requestId: route.requestId,
+          },
+        }));
+      })
+      .catch((error) => {
+        console.warn(`${logPrefix} desktop action reply failed for ${route.threadId}: ${error.message}`);
+        sendApplicationResponse(JSON.stringify({
+          id: responseMessage.id,
+          error: {
+            code: -32000,
+            message: "Could not send this action to Codex on the Mac.",
+          },
+        }));
+      });
+  }
+
+  function queueThreadChange(threadId, change) {
+    if (!change || typeof change !== "object") {
+      return;
+    }
+
+    const queuedChanges = queuedChangesByThreadId.get(threadId) || [];
+    queuedChanges.push(change);
+    queuedChangesByThreadId.set(threadId, queuedChanges);
+  }
+
+  function recoverThreadBaseline(threadId) {
+    if (typeof readConversationState !== "function"
+      || recoveringThreadIds.has(threadId)
+      || rawStatesByThreadId.has(threadId)) {
+      return;
+    }
+
+    recoveringThreadIds.add(threadId);
+    Promise.resolve()
+      .then(() => readConversationState(threadId))
+      .then((baselineState) => {
+        if (!baselineState || typeof baselineState !== "object") {
+          return;
+        }
+
+        let nextState = cloneJSON(baselineState);
+        const queuedChanges = queuedChangesByThreadId.get(threadId) || [];
+        queuedChangesByThreadId.delete(threadId);
+        for (const change of queuedChanges) {
+          nextState = applyConversationStateChange(nextState, change) || nextState;
+        }
+
+        rawStatesByThreadId.set(threadId, nextState);
+        syncProjectedActions(threadId, projectPendingDesktopActions(threadId, nextState));
+      })
+      .catch((error) => {
+        console.warn(`${logPrefix} desktop IPC baseline recovery failed for ${threadId}: ${error.message}`);
+      })
+      .finally(() => {
+        recoveringThreadIds.delete(threadId);
+      });
+  }
+
+  return {
+    observeInbound,
+    stopAll,
+  };
+}
+
+// Minimal IPC client for Litter's length-prefixed Codex desktop bus.
+function createDesktopIpcClient({
+  socketPath,
+  netModule,
+  now,
+  requestTimeoutMs,
+  logPrefix,
+  onEnvelope,
+  onDisconnect,
+}) {
+  let socket = null;
+  let clientId = "";
+  let isConnecting = false;
+  let readBuffer = Buffer.alloc(0);
+  const pendingRequests = new Map();
+
+  function ensureConnected() {
+    if (socket || isConnecting) {
+      return;
+    }
+
+    isConnecting = true;
+    const nextSocket = netModule.createConnection(socketPath);
+    socket = nextSocket;
+
+    nextSocket.on("connect", () => {
+      isConnecting = false;
+      sendRequest("initialize", { clientType: "remodex-bridge" })
+        .then((result) => {
+          clientId = readString(result?.clientId) || clientId;
+        })
+        .catch((error) => {
+          console.warn(`${logPrefix} desktop IPC initialize failed: ${error.message}`);
+          close();
+        });
+    });
+    nextSocket.on("data", handleData);
+    nextSocket.on("close", handleClose);
+    nextSocket.on("error", (error) => {
+      if (error?.code !== "ENOENT" && error?.code !== "ECONNREFUSED") {
+        console.warn(`${logPrefix} desktop IPC connection failed: ${error.message}`);
+      }
+    });
+  }
+
+  function sendRequest(method, params) {
+    ensureConnected();
+    if (!socket || socket.destroyed) {
+      return Promise.reject(new Error("Desktop IPC is not connected."));
+    }
+
+    const requestId = `remodex-${now().toString(36)}-${Math.random().toString(16).slice(2)}`;
+    const envelope = {
+      type: "request",
+      requestId,
+      sourceClientId: method === "initialize" ? "initializing-client" : clientId || "remodex-bridge",
+      version: METHOD_VERSION_BY_NAME.get(method) || 1,
+      method,
+      params: params || {},
+    };
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        pendingRequests.delete(requestId);
+        reject(new Error(`Desktop IPC request timed out: ${method}`));
+      }, requestTimeoutMs);
+      timeout.unref?.();
+
+      pendingRequests.set(requestId, {
+        method,
+        resolve,
+        reject,
+        timeout,
+      });
+      writeFrame(socket, JSON.stringify(envelope), (error) => {
+        if (!error) {
+          return;
+        }
+
+        clearTimeout(timeout);
+        pendingRequests.delete(requestId);
+        reject(error);
+      });
+    });
+  }
+
+  function handleData(chunk) {
+    readBuffer = Buffer.concat([readBuffer, chunk]);
+    while (readBuffer.length >= FRAME_HEADER_BYTES) {
+      const frameLength = readBuffer.readUInt32LE(0);
+      if (frameLength > MAX_FRAME_BYTES) {
+        close();
+        return;
+      }
+      if (readBuffer.length < FRAME_HEADER_BYTES + frameLength) {
+        return;
+      }
+
+      const payload = readBuffer.slice(FRAME_HEADER_BYTES, FRAME_HEADER_BYTES + frameLength).toString("utf8");
+      readBuffer = readBuffer.slice(FRAME_HEADER_BYTES + frameLength);
+      const envelope = safeParseJSON(payload);
+      if (envelope) {
+        dispatchEnvelope(envelope);
+      }
+    }
+  }
+
+  function dispatchEnvelope(envelope) {
+    if (envelope.type === "client-discovery-request") {
+      writeEnvelope({
+        type: "client-discovery-response",
+        requestId: envelope.requestId,
+        response: {
+          canHandle: false,
+        },
+      });
+      return;
+    }
+
+    if (envelope.type === "response") {
+      const requestId = requestIdKey(envelope.requestId);
+      const waiter = requestId ? pendingRequests.get(requestId) : null;
+      if (!waiter) {
+        return;
+      }
+
+      pendingRequests.delete(requestId);
+      clearTimeout(waiter.timeout);
+      if (envelope.resultType === "error") {
+        waiter.reject(new Error(envelope.error || `Desktop IPC request failed: ${waiter.method}`));
+        return;
+      }
+
+      waiter.resolve(envelope.result ?? null);
+      return;
+    }
+
+    onEnvelope(envelope);
+  }
+
+  function handleClose() {
+    socket = null;
+    clientId = "";
+    isConnecting = false;
+    readBuffer = Buffer.alloc(0);
+    for (const waiter of pendingRequests.values()) {
+      clearTimeout(waiter.timeout);
+      waiter.reject(new Error("Desktop IPC connection closed."));
+    }
+    pendingRequests.clear();
+    onDisconnect();
+  }
+
+  function close() {
+    if (!socket) {
+      return;
+    }
+
+    const nextSocket = socket;
+    socket = null;
+    nextSocket.destroy();
+  }
+
+  function writeEnvelope(envelope, callback = () => {}) {
+    if (!socket || socket.destroyed) {
+      callback(new Error("Desktop IPC is not connected."));
+      return;
+    }
+
+    writeFrame(socket, JSON.stringify(envelope), callback);
+  }
+
+  return {
+    ensureConnected,
+    sendRequest,
+    close,
+  };
+}
+
+function desktopFollowerPayloadForResponse(route, responseMessage) {
+  const method = REPLY_METHOD_BY_ACTION_METHOD.get(route.method);
+  if (!method || responseMessage?.error) {
+    return null;
+  }
+
+  if (route.method === "item/tool/requestUserInput") {
+    const answers = responseMessage?.result?.answers;
+    if (!answers || typeof answers !== "object" || Array.isArray(answers)) {
+      return null;
+    }
+
+    return {
+      method,
+      params: {
+        conversationId: route.threadId,
+        requestId: route.requestId,
+        response: {
+          answers,
+        },
+      },
+    };
+  }
+
+  const decision = readString(responseMessage?.result?.decision);
+  if (!APPROVAL_DECISIONS.has(decision)) {
+    return null;
+  }
+
+  return {
+    method,
+    params: {
+      conversationId: route.threadId,
+      requestId: route.requestId,
+      decision,
+    },
+  };
+}
+
+function projectPendingDesktopActions(threadId, conversationState) {
+  const requests = Array.isArray(conversationState?.requests) ? conversationState.requests : [];
+  return requests
+    .filter((request) => request && request.completed !== true)
+    .filter((request) => ACTION_METHODS.has(readString(request.method)))
+    .map((request) => projectPendingDesktopAction(threadId, request))
+    .filter(Boolean);
+}
+
+function projectPendingDesktopAction(threadId, request) {
+  const requestId = requestIdKey(request.id);
+  const method = readString(request.method);
+  const params = request.params && typeof request.params === "object" && !Array.isArray(request.params)
+    ? request.params
+    : {};
+  if (!requestId || !method) {
+    return null;
+  }
+
+  if (method === "item/tool/requestUserInput") {
+    const questions = Array.isArray(params.questions) ? params.questions : [];
+    if (questions.length === 0) {
+      return null;
+    }
+  }
+
+  return {
+    id: requestId,
+    method,
+    params: {
+      ...params,
+      threadId: readString(params.threadId) || readString(params.thread_id) || threadId,
+    },
+  };
+}
+
+function applyConversationStateChange(previousState, change) {
+  if (!change || typeof change !== "object") {
+    return null;
+  }
+
+  if (change.type === "snapshot" || change.type === "Snapshot") {
+    return cloneJSON(change.conversationState || change.conversation_state || {});
+  }
+
+  if (change.type !== "patches" && change.type !== "Patches") {
+    return previousState || null;
+  }
+
+  const patches = Array.isArray(change.patches) ? change.patches : [];
+  if (!previousState || patches.length === 0) {
+    return previousState || null;
+  }
+
+  const nextState = cloneJSON(previousState);
+  for (const patch of patches) {
+    applyImmerPatch(nextState, patch);
+  }
+  return nextState;
+}
+
+function isPatchChange(change) {
+  return change?.type === "patches" || change?.type === "Patches";
+}
+
+function seedConversationStateFromThreadRead(response) {
+  const conversationState = response?.conversationState || response?.conversation_state;
+  if (conversationState && typeof conversationState === "object" && !Array.isArray(conversationState)) {
+    return cloneJSON(conversationState);
+  }
+
+  const thread = response?.thread && typeof response.thread === "object" && !Array.isArray(response.thread)
+    ? response.thread
+    : {};
+  return {
+    turns: Array.isArray(thread.turns) ? cloneJSON(thread.turns) : [],
+    requests: Array.isArray(thread.requests) ? cloneJSON(thread.requests) : [],
+  };
+}
+
+function applyImmerPatch(target, patch) {
+  const patchPath = Array.isArray(patch?.path) ? patch.path : [];
+  const op = readString(patch?.op).toLowerCase();
+  if (!op || patchPath.length === 0) {
+    return;
+  }
+
+  let parent = target;
+  for (let index = 0; index < patchPath.length - 1; index += 1) {
+    parent = parent?.[patchPath[index]];
+    if (parent == null) {
+      return;
+    }
+  }
+
+  const key = patchPath[patchPath.length - 1];
+  if (op === "remove") {
+    if (Array.isArray(parent) && Number.isInteger(key)) {
+      parent.splice(key, 1);
+    } else if (parent && typeof parent === "object") {
+      delete parent[key];
+    }
+    return;
+  }
+
+  if (op === "add" || op === "replace") {
+    if (Array.isArray(parent) && Number.isInteger(key)) {
+      if (op === "add") {
+        parent.splice(key, 0, patch.value);
+      } else {
+        parent[key] = patch.value;
+      }
+    } else if (parent && typeof parent === "object") {
+      parent[key] = patch.value;
+    }
+  }
+}
+
+function writeFrame(socket, payload, callback) {
+  const body = Buffer.from(payload, "utf8");
+  const header = Buffer.alloc(FRAME_HEADER_BYTES);
+  header.writeUInt32LE(body.length, 0);
+  socket.write(Buffer.concat([header, body]), callback);
+}
+
+function resolveDefaultIpcSocketPath() {
+  const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+  return path.join(os.tmpdir(), "codex-ipc", `ipc-${uid}.sock`);
+}
+
+function readThreadId(params) {
+  return readString(params?.threadId)
+    || readString(params?.thread_id)
+    || readString(params?.conversationId)
+    || readString(params?.conversation_id);
+}
+
+function requestIdKey(value) {
+  if (typeof value === "string" && value) {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  return "";
+}
+
+function readString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+function cloneJSON(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function safeParseJSON(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  applyConversationStateChange,
+  createDesktopIpcActionFollower,
+  desktopFollowerPayloadForResponse,
+  projectPendingDesktopActions,
+  resolveDefaultIpcSocketPath,
+  seedConversationStateFromThreadRead,
+};

package/src/git-handler.js

@@ -14,11 +14,13 @@ const { promisify } = require("util");
 const execFileAsync = promisify(execFile);
 const GIT_TIMEOUT_MS = 30_000;
 const GIT_DRAFT_TIMEOUT_MS = 120_000;
+const GITHUB_CLI_TIMEOUT_MS = 120_000;
 const GIT_DRAFT_PATCH_MAX_BYTES = 80_000;
 const EMPTY_TREE_HASH = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const DEFAULT_GIT_WRITER_MODEL = "gpt-5.4-mini";
 
 let runStructuredCodexJsonImpl = runStructuredCodexJson;
+let runGitHubCliImpl = runGitHubCli;
 
 function resolveGitWriterModel(rawModel) {
   const trimmed = typeof rawModel === "string" ? rawModel.trim() : "";
@@ -123,6 +125,10 @@ async function handleGitMethod(method, params, options = {}) {
       return gitRemoteUrl(cwd);
     case "git/generatePullRequestDraft":
       return gitGeneratePullRequestDraft(cwd, params, options);
+    case "git/createPullRequest":
+      return gitCreatePullRequest(cwd, params, options);
+    case "git/runStackedAction":
+      return gitRunStackedAction(cwd, params, options);
     case "git/branchesWithStatus":
       return gitBranchesWithStatus(cwd);
     default:
@@ -400,7 +406,7 @@ async function gitPush(cwd) {
         pushErr.message?.includes("no upstream") ||
         pushErr.message?.includes("has no upstream branch")
       ) {
-        await git(cwd, "push", "--set-upstream", "origin", branch);
+        await git(cwd, "push", "--set-upstream", remote, branch);
       } else {
         throw pushErr;
       }
@@ -963,6 +969,282 @@ async function gitRemoteUrl(cwd) {
   return { url: raw, ownerRepo };
 }
 
+// ─── Git Stacked Actions / Pull Requests ─────────────────────
+
+async function gitRunStackedAction(cwd, params, options = {}) {
+  const action = normalizeStackedGitAction(params.action);
+  const initialStatus = await gitStatus(cwd);
+  const wantsCommit = action === "commit" || action === "commit_push" || action === "commit_push_pr";
+  const wantsPr = action === "create_pr" || action === "commit_push_pr";
+
+  if (params.featureBranch === true) {
+    await gitCreateFeatureBranch(cwd, params);
+  }
+
+  const branch = await currentBranchName(cwd);
+  const result = {
+    action,
+    branch: {
+      status: params.featureBranch === true ? "created" : "skipped_not_requested",
+      name: params.featureBranch === true ? branch : undefined,
+    },
+    commit: { status: "skipped_not_requested" },
+    push: { status: "skipped_not_requested" },
+    pr: { status: "skipped_not_requested" },
+    status: initialStatus,
+  };
+
+  if (action === "push" && initialStatus.dirty) {
+    throw gitError("dirty_worktree", "Commit or stash local changes before pushing.");
+  }
+  if (action === "create_pr" && initialStatus.dirty) {
+    throw gitError("dirty_worktree", "Commit local changes before creating a PR.");
+  }
+
+  if (wantsCommit) {
+    const statusBeforeCommit = await gitStatus(cwd);
+    if (statusBeforeCommit.dirty) {
+      const commitResult = await gitCommit(cwd, {
+        message: params.commitMessage || params.message,
+      });
+      result.commit = {
+        status: "created",
+        ...commitResult,
+        commitSha: commitResult.hash,
+        subject: firstCommitMessageLine(params.commitMessage || params.message),
+      };
+    } else if (action === "commit") {
+      throw gitError("nothing_to_commit", "Nothing to commit.");
+    } else {
+      result.commit = { status: "skipped_clean" };
+    }
+  }
+
+  const statusBeforePush = await gitStatus(cwd);
+  const shouldPush =
+    action === "push" ||
+    action === "commit_push" ||
+    action === "commit_push_pr" ||
+    (action === "create_pr" && (!statusBeforePush.tracking || statusBeforePush.ahead > 0));
+
+  if (shouldPush) {
+    if (action === "push" && !statusBeforePush.canPush) {
+      throw gitError("nothing_to_push", "Nothing to push.");
+    }
+    if (action === "commit_push" && result.commit.status === "skipped_clean" && !statusBeforePush.canPush) {
+      throw gitError("nothing_to_commit", "Nothing to commit or push.");
+    }
+    if (statusBeforePush.dirty) {
+      throw gitError("dirty_worktree", "Commit or stash local changes before pushing.");
+    }
+    result.push = {
+      state: "pushed",
+      ...(await gitPush(cwd)),
+    };
+  }
+
+  if (wantsPr) {
+    result.pr = await gitCreatePullRequest(cwd, {
+      ...params,
+      pushBeforeCreate: false,
+    }, options);
+  }
+
+  result.status = await gitStatus(cwd);
+  return result;
+}
+
+async function gitCreatePullRequest(cwd, params, options = {}) {
+  const status = await gitStatus(cwd);
+  if (status.dirty) {
+    throw gitError("dirty_worktree", "Commit local changes before creating a PR.");
+  }
+
+  const branch = status.branch || await currentBranchName(cwd);
+  if (!branch || branch === "HEAD") {
+    throw gitError("no_branch", "No current branch found.");
+  }
+
+  if (params.pushBeforeCreate !== false && (!status.tracking || status.ahead > 0)) {
+    await gitPush(cwd);
+  }
+
+  const branchResult = await gitBranches(cwd);
+  const baseBranch = resolveBaseBranchName(params.baseBranch, branchResult.default || branchResult.defaultBranch);
+  if (!baseBranch) {
+    throw gitError("no_default_branch", "Could not determine the repository default branch.");
+  }
+  if (baseBranch === branch) {
+    throw gitError(
+      "pull_request_same_branch",
+      `Cannot create a pull request from '${branch}' into itself. Create or switch to a feature branch first.`
+    );
+  }
+
+  await ensureGitHubCliReady(cwd);
+  const existing = await findOpenPullRequest(cwd, branch);
+  if (existing) {
+    return pullRequestResult("opened_existing", existing, baseBranch, branch);
+  }
+
+  const draft = await generatePullRequestDraftOrFallback(cwd, params, options, baseBranch, branch);
+  const bodyFile = path.join(os.tmpdir(), `remodex-pr-body-${process.pid}-${Date.now()}-${randomBytes(4).toString("hex")}.md`);
+  fs.writeFileSync(bodyFile, draft.body, "utf8");
+
+  let createOutput = null;
+  try {
+    createOutput = await gitHubCli(cwd, [
+      "pr",
+      "create",
+      "--base",
+      baseBranch,
+      "--head",
+      branch,
+      "--title",
+      draft.title,
+      "--body-file",
+      bodyFile,
+    ]);
+  } catch (error) {
+    const existingFromError = await findOpenPullRequest(cwd, branch).catch(() => null);
+    if (existingFromError || isPullRequestAlreadyExistsMessage(error.message)) {
+      return pullRequestResult("opened_existing", existingFromError, baseBranch, branch, draft.title);
+    }
+    throw error;
+  } finally {
+    fs.rmSync(bodyFile, { force: true });
+  }
+
+  const created = await findOpenPullRequest(cwd, branch).catch(() => null);
+  const createdUrl = parsePullRequestUrlFromText(`${createOutput?.stdout || ""}\n${createOutput?.stderr || ""}`);
+  return pullRequestResult("created", created, baseBranch, branch, draft.title, createdUrl);
+}
+
+function normalizeStackedGitAction(rawAction) {
+  const action = typeof rawAction === "string" ? rawAction.trim() : "";
+  if (["commit", "push", "create_pr", "commit_push", "commit_push_pr"].includes(action)) {
+    return action;
+  }
+  throw gitError("invalid_git_action", "Unknown git action.");
+}
+
+async function gitCreateFeatureBranch(cwd, params) {
+  const requestedName = normalizeNonEmptyLine(params.featureBranchName || params.branchName);
+  const branchName = requestedName || await defaultFeatureBranchName(cwd, params);
+  await assertValidCreatedBranchName(cwd, branchName);
+  if (await branchExists(cwd, branchName)) {
+    throw gitError("branch_exists", `Branch '${branchName}' already exists.`);
+  }
+  await git(cwd, "checkout", "-b", branchName);
+  return branchName;
+}
+
+async function defaultFeatureBranchName(cwd, params) {
+  const prefix = normalizeNonEmptyLine(params.featureBranchPrefix) || "remodex/mobile-pr";
+  const timestamp = new Date().toISOString().replace(/[-:T.Z]/g, "").slice(0, 14);
+  const base = `${prefix}-${timestamp}`;
+  let candidate = base;
+  for (let index = 2; await branchExists(cwd, candidate); index += 1) {
+    candidate = `${base}-${index}`;
+  }
+  return candidate;
+}
+
+async function branchExists(cwd, branchName) {
+  try {
+    await git(cwd, "show-ref", "--verify", "--quiet", `refs/heads/${branchName}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function currentBranchName(cwd) {
+  return (await git(cwd, "rev-parse", "--abbrev-ref", "HEAD")).trim();
+}
+
+async function generatePullRequestDraftOrFallback(cwd, params, options, baseBranch, branch) {
+  try {
+    return await gitGeneratePullRequestDraft(cwd, { ...params, baseBranch }, options);
+  } catch (error) {
+    if (error?.errorCode && error.errorCode !== "pull_request_draft_generation_failed") {
+      throw error;
+    }
+    return {
+      title: `Update ${branch}`,
+      body: [
+        "## Summary",
+        `- Prepare changes from \`${branch}\` for review.`,
+        "",
+        "## Testing",
+        "- Not run from Remodex.",
+        "",
+        "## Notes",
+        `- Base branch: \`${baseBranch}\`.`,
+      ].join("\n"),
+    };
+  }
+}
+
+function firstCommitMessageLine(message) {
+  return normalizeNonEmptyLine(message) || "Changes from Remodex";
+}
+
+async function ensureGitHubCliReady(cwd) {
+  try {
+    await gitHubCli(cwd, ["auth", "status"]);
+  } catch (error) {
+    if (error?.errorCode) {
+      throw error;
+    }
+    throw gitError("github_cli_unavailable", error.message || "GitHub CLI is unavailable.");
+  }
+}
+
+async function findOpenPullRequest(cwd, branch) {
+  const output = await gitHubCli(cwd, [
+    "pr",
+    "list",
+    "--head",
+    branch,
+    "--state",
+    "open",
+    "--limit",
+    "1",
+    "--json",
+    "number,title,url,baseRefName,headRefName,state",
+  ]);
+  const pullRequests = JSON.parse(output.stdout.trim() || "[]");
+  return Array.isArray(pullRequests) ? pullRequests[0] || null : null;
+}
+
+function pullRequestResult(status, pullRequest, baseBranch, branch, fallbackTitle = "", fallbackUrl = null) {
+  return {
+    status,
+    url: pullRequest?.url || fallbackUrl || null,
+    number: pullRequest?.number || null,
+    baseBranch: pullRequest?.baseRefName || baseBranch,
+    headBranch: pullRequest?.headRefName || branch,
+    title: pullRequest?.title || fallbackTitle || "",
+  };
+}
+
+function isPullRequestAlreadyExistsMessage(message) {
+  return typeof message === "string" && /pull request .*already exists|already exists.*pull request/i.test(message);
+}
+
+function parsePullRequestUrlFromText(text) {
+  if (typeof text !== "string") {
+    return null;
+  }
+  const match = text.match(/https:\/\/github\.com\/[^\s"'<>]+\/pull\/\d+/);
+  return match ? match[0] : null;
+}
+
+async function gitHubCli(cwd, args) {
+  return runGitHubCliImpl(cwd, args);
+}
+
 async function buildCommitDraftContext(cwd) {
   const [statusResult, repoRoot] = await Promise.all([
     gitStatus(cwd),
@@ -1010,7 +1292,7 @@ async function buildPullRequestDraftContext(cwd, params) {
     throw gitError("no_default_branch", "Could not determine the repository default branch.");
   }
 
-  const baseRef = await resolveExistingBranchRef(cwd, baseBranch);
+  const baseRef = await resolvePullRequestBaseRef(cwd, baseBranch);
   const mergeBase = (await git(cwd, "merge-base", "HEAD", baseRef)).trim();
   const patch = truncateDraftPatch(
     (await git(cwd, "diff", "--binary", "--find-renames", `${mergeBase}..HEAD`)).trim()
@@ -1041,16 +1323,17 @@ async function buildPullRequestDraftContext(cwd, params) {
   };
 }
 
-async function resolveExistingBranchRef(cwd, branchName) {
+// PRs compare against the remote base when possible, matching GitHub's base branch.
+async function resolvePullRequestBaseRef(cwd, branchName) {
   const localRef = `refs/heads/${branchName}`;
   const remoteRef = `refs/remotes/origin/${branchName}`;
 
-  if (await refExists(cwd, localRef)) {
-    return localRef;
-  }
   if (await refExists(cwd, remoteRef)) {
     return remoteRef;
   }
+  if (await refExists(cwd, localRef)) {
+    return localRef;
+  }
 
   return branchName;
 }
@@ -2154,6 +2437,22 @@ function git(cwd, ...args) {
     });
 }
 
+// Runs GitHub CLI in the same working tree so PR creation respects local auth and remotes.
+function runGitHubCli(cwd, args) {
+  return execFileAsync("gh", args, { cwd, timeout: GITHUB_CLI_TIMEOUT_MS })
+    .then(({ stdout, stderr }) => ({ stdout, stderr }))
+    .catch((err) => {
+      const detail = (err.stderr || err.message || "").trim();
+      if (err.code === "ENOENT") {
+        throw gitError("github_cli_unavailable", "GitHub CLI (`gh`) is required but is not available on PATH.");
+      }
+      if (/not logged into|not authenticated|gh auth login/i.test(detail)) {
+        throw gitError("github_cli_unauthenticated", "GitHub CLI is not authenticated. Run `gh auth login` on this Mac and retry.");
+      }
+      throw gitError("github_cli_failed", detail || "GitHub CLI command failed.");
+    });
+}
+
 async function revListCounts(cwd) {
   const output = await git(cwd, "rev-list", "--left-right", "--count", "HEAD...@{u}");
   const parts = output.trim().split(/\s+/);
@@ -2339,6 +2638,8 @@ module.exports = {
   __test: {
     gitGenerateCommitMessage,
     gitGeneratePullRequestDraft,
+    gitCreatePullRequest,
+    gitRunStackedAction,
     threadGenerateTitle,
     threadNameSet,
     gitBranches,
@@ -2367,5 +2668,11 @@ module.exports = {
     resetRunStructuredCodexJsonImplementation() {
       runStructuredCodexJsonImpl = runStructuredCodexJson;
     },
+    setRunGitHubCliImplementation(fn) {
+      runGitHubCliImpl = typeof fn === "function" ? fn : runGitHubCli;
+    },
+    resetRunGitHubCliImplementation() {
+      runGitHubCliImpl = runGitHubCli;
+    },
   },
 };

package/src/package-version-status.js

@@ -10,7 +10,7 @@ const { version: installedVersion = "" } = require("../package.json");
 const DEFAULT_CACHE_TTL_MS = 30 * 60 * 1000;
 const DEFAULT_EMPTY_CACHE_RETRY_MS = 60 * 1000;
 const DEFAULT_INITIAL_FETCH_WAIT_MS = 250;
-const REMODEX_REGISTRY_URL = "https://registry.npmjs.org/remodex/latest";
+const REMODEX_REGISTRY_URL = "https://registry.npmjs.org/@makerbi%2fremodex/latest";
 
 function createBridgePackageVersionStatusReader({
   cacheTtlMs = DEFAULT_CACHE_TTL_MS,

package/src/workspace-handler.js

@@ -132,12 +132,12 @@ async function workspaceReadImage(params) {
     throw workspaceError("image_not_found", "The image file no longer exists on this Mac.");
   }
 
-  const [realRepoRoot, realTempRoots] = await Promise.all([
-    cwd ? resolveRepoRoot(cwd).then(realpathOrNull).catch(() => null) : null,
+  const [realWorkspaceRoot, realTempRoots] = await Promise.all([
+    cwd ? resolveImageWorkspaceRoot(cwd) : null,
     realTemporaryImageRoots(),
   ]);
   const isAllowed =
-    (realRepoRoot && isPathInside(realImagePath, realRepoRoot))
+    (realWorkspaceRoot && isPathInside(realImagePath, realWorkspaceRoot))
     || (realGeneratedImagesRoot && isPathInside(realImagePath, realGeneratedImagesRoot))
     || realTempRoots.some((tempRoot) => isPathInside(realImagePath, tempRoot));
   if (!isAllowed) {
@@ -212,6 +212,26 @@ async function realTemporaryImageRoots() {
   return Array.from(new Set(roots.filter(Boolean)));
 }
 
+// Image previews are read-only, so non-git Codex scratch workspaces can be scoped to their cwd.
+async function resolveImageWorkspaceRoot(cwd) {
+  const realRepoRoot = await resolveRepoRoot(cwd).then(realpathOrNull).catch(() => null);
+  if (realRepoRoot) {
+    return realRepoRoot;
+  }
+
+  const realCwd = await realpathOrNull(cwd);
+  if (!realCwd || isBroadWorkspaceRoot(realCwd)) {
+    return null;
+  }
+  return realCwd;
+}
+
+function isBroadWorkspaceRoot(candidatePath) {
+  const normalized = path.resolve(candidatePath);
+  return normalized === path.parse(normalized).root
+    || normalized === path.resolve(os.homedir());
+}
+
 async function readPreviewImageData(imagePath, maxPixelDimension, originalByteLength) {
   if (!usesSipsImagePreview()) {
     if (originalByteLength <= MAX_IMAGE_PREVIEW_READ_BYTES) {