@makerbi/remodex 2.3.2 → 2.5.6

package/bin/remodex.js

@@ -16,6 +16,7 @@ const {
   startBridge,
   startMacOSBridgeService,
   stopMacOSBridgeService,
+  uninstallMacOSBridgeService,
   resetBridgePairing,
   openLastActiveThread,
   watchThreadRollout,
@@ -33,6 +34,7 @@ const defaultDeps = {
   startBridge,
   startMacOSBridgeService,
   stopMacOSBridgeService,
+  uninstallMacOSBridgeService,
   resetBridgePairing,
   openLastActiveThread,
   watchThreadRollout,
@@ -195,6 +197,27 @@ async function main({
     return;
   }
 
+  if (command === "uninstall-service") {
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    const result = deps.uninstallMacOSBridgeService();
+    emitResult({
+      payload: {
+        ok: true,
+        currentVersion: version,
+        plistPath: result?.plistPath,
+        removed: result?.removed,
+      },
+      message: "[remodex] Removed the macOS bridge service. You can now run `npm uninstall -g @makerbi/remodex`.",
+      jsonOutput,
+      consoleImpl,
+    });
+    return;
+  }
+
   if (command === "status") {
     assertMacOSCommand(command, {
       platform,
@@ -280,9 +303,9 @@ async function main({
   consoleImpl.error(`Unknown command: ${command}`);
   consoleImpl.error(
     "Usage: remodex up | remodex run [--extra-device|--extra-devices=N] | remodex start | remodex restart | "
-    + "remodex qr | remodex pair | remodex stop | remodex status | "
+    + "remodex qr | remodex pair | remodex stop | remodex uninstall-service | remodex status | "
     + "remodex reset-pairing | remodex resume | remodex watch [threadId] | remodex --version | "
-    + "append --json to start/restart/qr/pair/stop/status/reset-pairing/resume for machine-readable output"
+    + "append --json to start/restart/qr/pair/stop/uninstall-service/status/reset-pairing/resume for machine-readable output"
   );
   exitImpl(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makerbi/remodex",
-  "version": "2.3.2",
+  "version": "2.5.6",
   "description": "Local bridge between Codex and the Remodex mobile app. Run `remodex up` to start.",
   "repository": {
     "type": "git",

package/src/bridge.js

@@ -54,7 +54,9 @@ const {
 const { createBridgeSecureTransport } = require("./secure-transport");
 const { createRolloutLiveMirrorController } = require("./rollout-live-mirror");
 const {
+  buildCompleteThreadReadParams,
   isContextualUserText,
+  isThreadTurnStateProbeRequest,
   isUserRoleItem,
   readUserItemText,
   sanitizeUserRoleItem,
@@ -66,6 +68,9 @@ const {
 } = require("./desktop-ipc-action-follower");
 const { createDesktopIpcLiveOwner } = require("./desktop-ipc-live-owner");
 const { createThreadRuntimeSettingsStore } = require("./thread-runtime-settings-store");
+const { createThreadListProvenanceEnricher } = require("./thread-list-provenance");
+const { createWorktreeOriginEnricher } = require("./worktree-origin");
+const { forEachThreadRowInResponse } = require("./thread-row-enrichment");
 const { version: bridgePackageVersion = "" } = require("../package.json");
 const {
   MINIMUM_SUPPORTED_IOS_APP_VERSION,
@@ -120,7 +125,7 @@ const RELAY_JSONL_FULL_ARTIFACT_FALLBACK_MAX_BYTES = Math.max(
   0,
   bufferConstants.MAX_STRING_LENGTH - (8 * 1024 * 1024)
 );
-const BRIDGE_PACKAGE_UPDATE_COMMAND = "npm install -g remodex@latest";
+const BRIDGE_PACKAGE_UPDATE_COMMAND = "npm install -g @makerbi/remodex@latest";
 const BRIDGE_PACKAGE_UPDATE_TIMEOUT_MS = 180_000;
 const BRIDGE_RESTART_AFTER_UPDATE_DELAY_MS = 750;
 const MODELS_WITHOUT_REASONING_SUMMARY = new Set([
@@ -476,6 +481,27 @@ function createThreadTurnsListFastPageCoordinator({
       canonicalRequest,
       fetchCanonical
     );
+    let timeoutId = null;
+    const deadline = new Promise((resolveDeadline) => {
+      timeoutId = setTimeoutImpl(() => resolveDeadline({ deadline: true }), waitMs);
+    });
+    const first = await Promise.race([canonicalOutcomePromise, deadline]);
+    if (timeoutId != null) {
+      clearTimeoutImpl(timeoutId);
+    }
+
+    if (first?.ok && !isEmptyTurnsListResponse(first.response)) {
+      forgetCanonicalFirstPage(canonicalFirstPageCacheKey, canonicalOutcomePromise);
+      return {
+        source: "canonical",
+        response: rebindThreadTurnsListResponseId(first.response, request.id),
+        usesJsonl: false,
+      };
+    }
+
+    // Deadline hit, canonical error, or an empty canonical page: only now pay
+    // for the synchronous rollout read, so a fast canonical response never
+    // blocks behind it and never delays itself.
     let jsonlFallback = null;
     try {
       jsonlFallback = await readJsonl(request);
@@ -500,38 +526,6 @@ function createThreadTurnsListFastPageCoordinator({
       };
     }
 
-    let timeoutId = null;
-    const deadline = new Promise((resolveDeadline) => {
-      timeoutId = setTimeoutImpl(() => resolveDeadline({ deadline: true }), waitMs);
-    });
-    const first = await Promise.race([canonicalOutcomePromise, deadline]);
-    if (timeoutId != null) {
-      clearTimeoutImpl(timeoutId);
-    }
-
-    if (first?.ok && !isEmptyTurnsListResponse(first.response)) {
-      if (shouldPreferJsonlFirstPage(first.response, jsonlFallback.response)) {
-        const token = rememberHandoff(threadId, canonicalOutcomePromise, jsonlFallback);
-        return {
-          source: "jsonl",
-          response: buildJsonlCanonicalHandoffResponse(
-            jsonlFallback.response,
-            request.id,
-            token,
-            firstTurnsListTurnId(jsonlFallback.response)
-          ),
-          usesJsonl: true,
-        };
-      }
-      forgetCanonicalFirstPage(canonicalFirstPageCacheKey, canonicalOutcomePromise);
-      return {
-        source: "canonical",
-        response: rebindThreadTurnsListResponseId(first.response, request.id),
-        usesJsonl: false,
-        jsonlFallback,
-      };
-    }
-
     const token = rememberHandoff(threadId, canonicalOutcomePromise, jsonlFallback);
     return {
       source: "jsonl",
@@ -577,6 +571,33 @@ function threadTurnsListHandoffDescriptor(cursor) {
   return { anchorTurnId, token };
 }
 
+// The bounded canonical page can read a busy mirrored run as closed for a
+// beat, which used to flap the phone's running state. When the rollout mirror
+// is actively tailing a real turn, ride its id along on the turn-state probe
+// as an advisory field; history pages stay untouched.
+function annotateTurnStateProbeWithMirrorActiveTurn(request, response, getMirrorActiveTurnId) {
+  if (!isThreadTurnStateProbeRequest(request)) {
+    return response;
+  }
+  const params = request?.params || {};
+  const threadId = normalizeNonEmptyString(params.threadId)
+    || normalizeNonEmptyString(params.thread_id);
+  const mirrorActiveTurnId = threadId ? getMirrorActiveTurnId?.(threadId) : null;
+  const result = response?.result;
+  if (!mirrorActiveTurnId || !result || typeof result !== "object" || Array.isArray(result)) {
+    return response;
+  }
+  // Page responses can come from the fast-page cache: never mutate a shared
+  // object, or the annotation would outlive the mirror on later replays.
+  return {
+    ...response,
+    result: {
+      ...result,
+      remodexMirrorActiveTurnId: mirrorActiveTurnId,
+    },
+  };
+}
+
 function canonicalThreadTurnsListRequest(request) {
   const params = { ...(request?.params || {}) };
   delete params.remodexRequireCanonical;
@@ -632,21 +653,6 @@ function buildJsonlCanonicalHandoffResponse(response, requestId, token, anchorTu
   };
 }
 
-function shouldPreferJsonlFirstPage(canonicalResponse, jsonlResponse) {
-  const canonicalResult = canonicalResponse?.result;
-  const jsonlResult = jsonlResponse?.result;
-  const canonicalTurnsKey = findTurnsListResultKey(canonicalResult);
-  const jsonlTurnsKey = findTurnsListResultKey(jsonlResult);
-  if (!canonicalTurnsKey || !jsonlTurnsKey) {
-    return false;
-  }
-  const jsonlTurn = jsonlResult[jsonlTurnsKey]?.[0];
-  const jsonlTurnId = turnListTurnIdentifier(jsonlTurn);
-  return Boolean(jsonlTurnId)
-    && !canonicalResult[canonicalTurnsKey].some((turn) => turnListTurnIdentifier(turn) === jsonlTurnId)
-    && shouldMergeLatestJsonlTurn(jsonlTurn);
-}
-
 function firstTurnsListTurnId(response) {
   const result = response?.result;
   const turnsKey = findTurnsListResultKey(result);
@@ -755,7 +761,10 @@ function startBridge({
   const relaySessionUrl = `${relayBaseUrl}/${sessionId}`;
   const notificationSecret = randomBytes(24).toString("hex");
   const desktopRefresher = new CodexDesktopRefresher({
-    enabled: config.refreshEnabled,
+    // IPC snapshots are accepted only after Codex mounts the route and
+    // announces itself as a follower. Auto-follow performs that one-time
+    // activation; refreshEnabled still controls the legacy reload workaround.
+    enabled: config.refreshEnabled || config.desktopAutoFollowEnabled === true,
     // With IPC live sync streaming content, deep-link refreshes are only needed
     // to navigate Desktop onto the phone-driven thread, not to reload content.
     navigationOnly: config.desktopIpcLiveSyncEnabled,
@@ -798,6 +807,8 @@ function startBridge({
   const jsonlTurnsListRolloutMissCacheByThread = new Map();
   const threadTurnsListFastPageCoordinator = createThreadTurnsListFastPageCoordinator();
   const threadRuntimeSettingsStore = createThreadRuntimeSettingsStore();
+  const threadListProvenanceEnricher = createThreadListProvenanceEnricher();
+  const worktreeOriginEnricher = createWorktreeOriginEnricher();
   const trackedForwardedRequestMethods = new Set([
     "account/login/start",
     "account/login/cancel",
@@ -863,7 +874,7 @@ function startBridge({
     ? createDesktopIpcActionFollower({
       sendApplicationResponse,
       readConversationState: async (threadId) => seedConversationStateFromThreadRead(
-        await sendCodexRequest("thread/read", { threadId })
+        await sendCodexRequest("thread/read", buildCompleteThreadReadParams(threadId))
       ),
       forwardToLocalCodex: (rawMessage) => {
         observeDesktopIpcLiveOwnerInbound(rawMessage);
@@ -876,6 +887,9 @@ function startBridge({
       runtimeSettingsStore: threadRuntimeSettingsStore,
       socketPath: config.desktopIpcSocketPath || undefined,
       snapshotDebounceMs: config.desktopIpcSnapshotDebounceMs,
+      onFollowerStateChanged(threadId, following) {
+        desktopRefresher.handleFollowerStateChanged(threadId, following);
+      },
     })
     : null;
   const desktopIpcLiveOwner = !config.codexEndpoint
@@ -888,6 +902,9 @@ function startBridge({
       runtimeSettingsStore: threadRuntimeSettingsStore,
       socketPath: config.desktopIpcSocketPath || undefined,
       snapshotDebounceMs: config.desktopIpcSnapshotDebounceMs,
+      onFollowerStateChanged(threadId, following) {
+        desktopRefresher.handleFollowerStateChanged(threadId, following);
+      },
     })
     : null;
   let contextUsageWatcher = null;
@@ -1152,7 +1169,6 @@ function startBridge({
       stopContextUsageWatcher();
       // Relay reconnects are transport-only: keep local live observers running
       // so their output can enter secure replay and catch up on the next resume.
-      desktopRefresher.handleTransportReset();
       scheduleRelayReconnect(code);
     });
 
@@ -1400,15 +1416,7 @@ function startBridge({
           }),
           readJsonl: (jsonlRequest) => maybeBuildJsonlThreadTurnsListFallback(jsonlRequest, null),
         });
-        let responsePayload = selection.response;
-        if (selection.source === "canonical" && selection.jsonlFallback?.response?.result) {
-          responsePayload = maybeMergeLatestJsonlTurnIntoTurnsListResponse(
-            request,
-            selection.response,
-            selection.jsonlFallback.response.result
-          ) || selection.response;
-        }
-        sendBridgeManagedThreadTurnsListResponse(request, responsePayload, respondOnce, {
+        sendBridgeManagedThreadTurnsListResponse(request, selection.response, respondOnce, {
           skipJsonlArtifactAugmentation: selection.usesJsonl,
         });
       } catch (error) {
@@ -1433,6 +1441,11 @@ function startBridge({
   function sendBridgeManagedThreadTurnsListResponse(request, response, sendResponse, {
     skipJsonlArtifactAugmentation = false,
   } = {}) {
+    response = annotateTurnStateProbeWithMirrorActiveTurn(
+      request,
+      response,
+      (threadId) => rolloutLiveMirror?.getActiveTurnId(threadId) || null
+    );
     const finalSanitizeContext = buildThreadTurnsListRelaySanitizeContext(request, {
       skipJsonlArtifactAugmentation,
     });
@@ -1751,7 +1764,12 @@ function startBridge({
     if (trackedRequest.method === "thread/list"
       || trackedRequest.method === "thread/read"
       || trackedRequest.method === "thread/resume") {
-      threadRuntimeSettingsStore.enrichResponse(trackedRequest.method, parsed);
+      // One walk over the rows for both enrichers instead of one traversal each.
+      forEachThreadRowInResponse(trackedRequest.method, parsed, (thread) => {
+        threadRuntimeSettingsStore.attachToThread(thread);
+        threadListProvenanceEnricher.attachToThread(thread);
+        worktreeOriginEnricher.attachToThread(thread);
+      });
       normalizedMessage = JSON.stringify(parsed);
     }
 
@@ -5109,6 +5127,7 @@ function shouldSuppressRolloutMirrorForThread(
 }
 
 module.exports = {
+  annotateTurnStateProbeWithMirrorActiveTurn,
   buildThreadTurnsListRelaySanitizeContext,
   buildHeartbeatBridgeStatus,
   buildRelayAccessTokenHeaders,

package/src/codex-desktop-refresher.js

@@ -18,6 +18,8 @@ const DEFAULT_MID_RUN_REFRESH_THROTTLE_MS = 3_000;
 const DEFAULT_ROLLOUT_LOOKUP_TIMEOUT_MS = 5_000;
 const DEFAULT_ROLLOUT_IDLE_TIMEOUT_MS = 10_000;
 const DEFAULT_CUSTOM_REFRESH_FAILURE_THRESHOLD = 3;
+const DEFAULT_FOLLOW_CONFIRM_TIMEOUT_MS = 1_500;
+const DEFAULT_FOLLOW_MAX_ATTEMPTS = 3;
 const REFRESH_SCRIPT_PATH = path.join(__dirname, "scripts", "codex-refresh.applescript");
 const NEW_THREAD_DEEP_LINK = "codex://threads/new";
 
@@ -44,6 +46,8 @@ class CodexDesktopRefresher {
     watchThreadRolloutFactory = createThreadRolloutActivityWatcher,
     refreshBackend = null,
     customRefreshFailureThreshold = DEFAULT_CUSTOM_REFRESH_FAILURE_THRESHOLD,
+    followConfirmTimeoutMs = DEFAULT_FOLLOW_CONFIRM_TIMEOUT_MS,
+    followMaxAttempts = DEFAULT_FOLLOW_MAX_ATTEMPTS,
   } = {}) {
     this.enabled = enabled;
     this.navigationOnly = navigationOnly;
@@ -62,6 +66,8 @@ class CodexDesktopRefresher {
     this.refreshBackend = refreshBackend
       || (this.refreshCommand ? "command" : (this.refreshExecutor ? "command" : "applescript"));
     this.customRefreshFailureThreshold = customRefreshFailureThreshold;
+    this.followConfirmTimeoutMs = followConfirmTimeoutMs;
+    this.followMaxAttempts = followMaxAttempts;
 
     this.mode = "idle";
     this.pendingNewThread = false;
@@ -84,6 +90,11 @@ class CodexDesktopRefresher {
     this.watchStartAt = 0;
     this.lastRolloutSize = null;
     this.stopWatcherAfterRefreshThreadId = null;
+    this.materializationPendingThreadIds = new Set();
+    this.followedThreadIds = new Set();
+    this.followAttemptsByThreadId = new Map();
+    this.followConfirmationTimersByThreadId = new Map();
+    this.followActivationSerial = 0;
     this.runtimeRefreshAvailable = enabled;
     this.consecutiveRefreshFailures = 0;
     this.unavailableLogged = false;
@@ -117,8 +128,19 @@ class CodexDesktopRefresher {
         return;
       }
 
+      if (this.navigationOnly && target.threadId) {
+        if (this.followedThreadIds.has(target.threadId)) {
+          this.log(`desktop follow already active thread=${target.threadId}`);
+          return;
+        }
+        if (this.materializationPendingThreadIds.has(target.threadId)) {
+          this.ensureWatcher(target.threadId);
+          return;
+        }
+      }
+
       this.queueRefresh("phone", target, `phone ${method}`);
-      if (target.threadId) {
+      if (target.threadId && !this.navigationOnly) {
         this.ensureWatcher(target.threadId);
       }
     }
@@ -149,16 +171,51 @@ class CodexDesktopRefresher {
 
     if (method === "thread/started") {
       const target = resolveOutboundTarget(method, parsed);
+      const shouldWaitForMaterialization = Boolean(
+        this.navigationOnly
+        && this.pendingNewThread
+        && target?.threadId
+      );
       this.pendingNewThread = false;
       this.clearFallbackTimer();
+      if (shouldWaitForMaterialization) {
+        this.materializationPendingThreadIds.add(target.threadId);
+        this.mode = "waiting_for_materialization";
+        this.ensureWatcher(target.threadId);
+        return;
+      }
       this.queueRefresh("phone", target, `codex ${method}`);
-      if (target?.threadId) {
+      if (target?.threadId && !this.navigationOnly) {
         this.mode = "watching_thread";
         this.ensureWatcher(target.threadId);
       }
     }
   }
 
+  // Codex emits this only after the thread route mounts and its renderer calls
+  // set-active-conversation. That is the authoritative proof that Desktop will
+  // accept the owner's snapshots instead of dropping them as unfollowed.
+  handleFollowerStateChanged(threadId, following) {
+    const normalizedThreadId = readString(threadId);
+    if (!normalizedThreadId) {
+      return;
+    }
+    if (!following) {
+      this.followedThreadIds.delete(normalizedThreadId);
+      return;
+    }
+
+    this.followedThreadIds.add(normalizedThreadId);
+    this.materializationPendingThreadIds.delete(normalizedThreadId);
+    this.followAttemptsByThreadId.delete(normalizedThreadId);
+    this.clearFollowConfirmationTimer(normalizedThreadId);
+    this.log(`desktop follow confirmed thread=${normalizedThreadId}`);
+    if (this.activeWatchedThreadId === normalizedThreadId) {
+      this.stopWatcher();
+      this.mode = "idle";
+    }
+  }
+
   // Stops volatile watcher/fallback state when transport drops or bridge exits.
   handleTransportReset() {
     this.clearRefreshTimer();
@@ -168,6 +225,9 @@ class CodexDesktopRefresher {
     this.mode = "idle";
     this.clearFallbackTimer();
     this.stopWatcher();
+    this.materializationPendingThreadIds.clear();
+    this.followedThreadIds.clear();
+    this.clearAllFollowConfirmationTimers();
   }
 
   queueRefresh(kind, target, reason) {
@@ -283,12 +343,29 @@ class CodexDesktopRefresher {
         && this.now() - this.lastRefreshAt < this.debounceMs
       ) {
         this.log(`refresh skipped (duplicate target): ${refreshSignature}`);
+      } else if (
+        this.navigationOnly
+        && targetThreadId
+        && this.followedThreadIds.has(targetThreadId)
+      ) {
+        this.log(`desktop follow confirmed before navigation thread=${targetThreadId}`);
       } else {
-        await this.executeRefresh(targetUrl);
+        const refreshTargetUrl = this.followActivationTargetUrl(
+          targetUrl,
+          targetThreadId
+        );
+        await this.executeRefresh(refreshTargetUrl);
         this.lastRefreshAt = this.now();
         this.lastRefreshSignature = refreshSignature;
         this.consecutiveRefreshFailures = 0;
         didRefresh = true;
+        if (
+          this.navigationOnly
+          && targetThreadId
+          && !this.followedThreadIds.has(targetThreadId)
+        ) {
+          this.scheduleFollowConfirmation(targetThreadId, targetUrl);
+        }
       }
       if (completionTurnId && didRefresh) {
         this.lastTurnIdRefreshed = completionTurnId;
@@ -355,7 +432,7 @@ class CodexDesktopRefresher {
 
   // Schedules a single low-cost fallback when a brand new thread id is still unknown.
   scheduleNewThreadFallback() {
-    if (!this.canRefresh()) {
+    if (!this.canRefresh() || this.navigationOnly) {
       return;
     }
 
@@ -386,7 +463,7 @@ class CodexDesktopRefresher {
 
   // Keeps one lightweight rollout watcher alive for the current Remodex-controlled thread.
   ensureWatcher(threadId) {
-    if (this.navigationOnly || !this.canRefresh() || !threadId) {
+    if (!this.canRefresh() || !threadId) {
       return;
     }
 
@@ -406,16 +483,19 @@ class CodexDesktopRefresher {
       onEvent: (event) => this.handleWatcherEvent(event),
       onIdle: () => {
         this.log(`rollout watcher idle thread=${threadId}`);
+        this.activateAfterMaterializationWait(threadId, "rollout watcher idle");
         this.stopWatcher();
         this.mode = this.pendingNewThread ? "pending_new_thread" : "idle";
       },
       onTimeout: () => {
         this.log(`rollout watcher timeout thread=${threadId}`);
+        this.activateAfterMaterializationWait(threadId, "rollout watcher timeout");
         this.stopWatcher();
         this.mode = this.pendingNewThread ? "pending_new_thread" : "idle";
       },
       onError: (error) => {
         this.log(`rollout watcher failed thread=${threadId}: ${error.message}`);
+        this.activateAfterMaterializationWait(threadId, "rollout watcher error");
         this.stopWatcher();
         this.mode = this.pendingNewThread ? "pending_new_thread" : "idle";
       },
@@ -451,10 +531,19 @@ class CodexDesktopRefresher {
     });
 
     if (event.reason === "materialized") {
+      this.materializationPendingThreadIds.delete(event.threadId);
       this.queueRefresh("rollout_materialized", {
         threadId: event.threadId,
         url: buildThreadDeepLink(event.threadId),
       }, `rollout ${event.reason}`);
+      if (this.navigationOnly) {
+        this.stopWatcher();
+        this.mode = "idle";
+      }
+      return;
+    }
+
+    if (this.navigationOnly) {
       return;
     }
 
@@ -513,6 +602,9 @@ class CodexDesktopRefresher {
     this.clearFallbackTimer();
     this.stopWatcher();
     this.clearPendingState();
+    this.materializationPendingThreadIds.clear();
+    this.followedThreadIds.clear();
+    this.clearAllFollowConfirmationTimers();
     this.mode = "idle";
 
     if (!this.unavailableLogged) {
@@ -529,6 +621,69 @@ class CodexDesktopRefresher {
   hasPendingRefreshWork() {
     return this.pendingCompletionRefresh || this.pendingRefreshKinds.size > 0;
   }
+
+  activateAfterMaterializationWait(threadId, reason) {
+    if (!this.navigationOnly || !this.materializationPendingThreadIds.delete(threadId)) {
+      return;
+    }
+    this.queueRefresh("materialization_fallback", {
+      threadId,
+      url: buildThreadDeepLink(threadId),
+    }, reason);
+  }
+
+  // Opening an already-active deep link is a no-op in Codex, so the route's
+  // set-active-conversation effect never re-announces following after an IPC
+  // reconnect. Every activation gets a unique query value: waiting for a failed
+  // plain attempt first leaves the first 1.5s of a phone turn invisible.
+  followActivationTargetUrl(targetUrl, threadId) {
+    if (!this.navigationOnly || !threadId) {
+      return targetUrl;
+    }
+    const resolvedTargetUrl = targetUrl || buildThreadDeepLink(threadId);
+    const separator = resolvedTargetUrl.includes("?") ? "&" : "?";
+    this.followActivationSerial += 1;
+    return `${resolvedTargetUrl}${separator}remodex-follow=${this.now()}-${this.followActivationSerial}`;
+  }
+
+  scheduleFollowConfirmation(threadId, targetUrl) {
+    this.clearFollowConfirmationTimer(threadId);
+    const attempts = (this.followAttemptsByThreadId.get(threadId) || 0) + 1;
+    this.followAttemptsByThreadId.set(threadId, attempts);
+    if (attempts >= this.followMaxAttempts) {
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      this.followConfirmationTimersByThreadId.delete(threadId);
+      if (this.followedThreadIds.has(threadId) || !this.canRefresh()) {
+        return;
+      }
+      this.queueRefresh("follow_retry", {
+        threadId,
+        url: targetUrl || buildThreadDeepLink(threadId),
+      }, `desktop follow not confirmed (attempt ${attempts + 1})`);
+    }, Math.max(0, this.followConfirmTimeoutMs));
+    timer.unref?.();
+    this.followConfirmationTimersByThreadId.set(threadId, timer);
+  }
+
+  clearFollowConfirmationTimer(threadId) {
+    const timer = this.followConfirmationTimersByThreadId.get(threadId);
+    if (!timer) {
+      return;
+    }
+    clearTimeout(timer);
+    this.followConfirmationTimersByThreadId.delete(threadId);
+  }
+
+  clearAllFollowConfirmationTimers() {
+    for (const timer of this.followConfirmationTimersByThreadId.values()) {
+      clearTimeout(timer);
+    }
+    this.followConfirmationTimersByThreadId.clear();
+    this.followAttemptsByThreadId.clear();
+  }
 }
 
 function readBridgeConfig({
@@ -573,6 +728,7 @@ function readBridgeConfig({
   );
   const explicitRefreshEnabled = readOptionalBooleanEnv(["REMODEX_REFRESH_ENABLED"], env);
   const explicitDesktopIpcLiveSyncEnabled = readOptionalBooleanEnv(["REMODEX_DESKTOP_IPC_LIVE_SYNC"], env);
+  const explicitDesktopAutoFollowEnabled = readOptionalBooleanEnv(["REMODEX_DESKTOP_AUTO_FOLLOW"], env);
   const explicitKeepMacAwakeEnabled = readOptionalBooleanEnv(["REMODEX_KEEP_MAC_AWAKE"], env);
   const persistedKeepMacAwakeEnabled = typeof daemonConfig.keepMacAwakeEnabled === "boolean"
     ? daemonConfig.keepMacAwakeEnabled
@@ -585,6 +741,14 @@ function readBridgeConfig({
     ? daemonConfig.refreshEnabled
     : null;
   const defaultRefreshEnabled = persistedRefreshEnabled == null ? false : persistedRefreshEnabled;
+  const desktopIpcLiveSyncEnabled = explicitDesktopIpcLiveSyncEnabled == null
+    ? true
+    : explicitDesktopIpcLiveSyncEnabled;
+  const defaultDesktopAutoFollowEnabled = (
+    platform === "darwin"
+    && !codexEndpoint
+    && desktopIpcLiveSyncEnabled
+  );
   return {
     relayUrl,
     relayAccessToken,
@@ -609,9 +773,10 @@ function readBridgeConfig({
       : explicitKeepMacAwakeEnabled,
     codexEndpoint,
     desktopIpcSocketPath: readFirstDefinedEnv(["REMODEX_DESKTOP_IPC_SOCKET"], "", env),
-    desktopIpcLiveSyncEnabled: explicitDesktopIpcLiveSyncEnabled == null
-      ? true
-      : explicitDesktopIpcLiveSyncEnabled,
+    desktopIpcLiveSyncEnabled,
+    desktopAutoFollowEnabled: explicitDesktopAutoFollowEnabled == null
+      ? defaultDesktopAutoFollowEnabled
+      : explicitDesktopAutoFollowEnabled,
     desktopIpcSnapshotDebounceMs: parseIntegerEnv(
       readFirstDefinedEnv(["REMODEX_DESKTOP_IPC_SNAPSHOT_DEBOUNCE_MS"], "75", env),
       75