@makerbi/remodex 2.3.0 → 2.3.2

package/package.json

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

package/src/bridge.js

@@ -148,6 +148,25 @@ const RELAY_TURNS_LIST_PREVIOUS_PAGINATION_RESULT_KEYS = new Set([
   "previousCursor",
   "previous_cursor",
 ]);
+
+function buildRelayUserAgentHeader({ version = bridgePackageVersion } = {}) {
+  const normalizedVersion = typeof version === "string" && version.trim()
+    ? version.trim().replace(/\s+/g, "-")
+    : "dev";
+  return `RemodexBridge/${normalizedVersion}`;
+}
+
+function buildRelayAccessTokenHeaders(config = {}, env = process.env) {
+  const token = normalizeNonEmptyString(
+    config.relayAccessToken
+      || env.REMODEX_RELAY_ACCESS_TOKEN
+      || env.PHODEX_RELAY_ACCESS_TOKEN
+  );
+  return token
+    ? { "x-remodex-relay-token": token }
+    : {};
+}
+
 const jsonlArtifactItemsCacheByThread = new Map();
 const jsonlThreadCwdCacheByThread = new Map();
 const FORWARDED_REQUEST_METHODS_MAX_SIZE = 500;
@@ -1078,8 +1097,10 @@ function startBridge({
       },
       // The relay uses this per-session secret to authenticate the first push registration.
       headers: {
+        "User-Agent": buildRelayUserAgentHeader(),
         "x-role": "mac",
         "x-notification-secret": notificationSecret,
+        ...buildRelayAccessTokenHeaders(config),
         ...buildMacRegistrationHeaders(deviceState, pairingSession),
       },
     });
@@ -5090,6 +5111,8 @@ function shouldSuppressRolloutMirrorForThread(
 module.exports = {
   buildThreadTurnsListRelaySanitizeContext,
   buildHeartbeatBridgeStatus,
+  buildRelayAccessTokenHeaders,
+  buildRelayUserAgentHeader,
   canonicalThreadTurnsListRequest,
   createMacOSBridgeWakeAssertion,
   createThreadTurnsListFastPageCoordinator,

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

@@ -11,6 +11,7 @@ const {
   createDesktopConversationProjector,
   desktopTurnsShareLogicalIdentity,
   matchDesktopTurnIdentityContinuities,
+  projectDesktopConversationStateToGoal,
   projectDesktopConversationStateToThread,
 } = require("./desktop-ipc-conversation-projector");
 const {
@@ -41,7 +42,12 @@ const BACKGROUND_DISCONNECT_GRACE_MS = 30_000;
 const MAX_ACTIVE_THREAD_IDS = 512;
 const DESKTOP_IPC_ACTION_SOURCE = "desktop-ipc-action-follower";
 const REMODEX_LIVE_OWNER_SOURCE = "desktop-ipc-live-owner";
-const DESKTOP_STATE_READ_METHODS = new Set(["thread/read", "thread/resume", "thread/turns/list"]);
+const DESKTOP_STATE_READ_METHODS = new Set([
+  "thread/read",
+  "thread/resume",
+  "thread/turns/list",
+  "thread/goal/get",
+]);
 // Sidebar refreshes should also keep the Litter subscription alive. Without
 // this, a phone with no selected chat never connects to the Desktop bus and
 // cannot discover runs that started on the Mac.
@@ -53,12 +59,21 @@ const DESKTOP_TURNS_CURSOR_PREFIX = "remodex-desktop-turns:";
 // (e.g. Desktop never saw the turn finish) and must not answer phone reads, or
 // the phone shows a phantom running indicator until real history loads.
 const STALE_ACTIVE_READ_MAX_AGE_MS = 20_000;
+const MAX_NORMALIZED_REVIEW_FINGERPRINTS_PER_THREAD = 128;
 const DESKTOP_FOLLOWER_REQUEST_METHODS = new Set([
   "turn/start",
   "turn/steer",
   "turn/interrupt",
   "thread/compact/start",
 ]);
+// These mutations have no Codex Desktop follower command. Never leak them to
+// the bridge's separate local app-server owner, which could create a competing
+// owner for the same persisted thread.
+const DESKTOP_OWNER_UNSUPPORTED_MUTATION_ERRORS = new Map([
+  ["review/start", "Start this review in Codex Desktop."],
+  ["thread/settings/update", "Change these thread settings in Codex Desktop."],
+  ["thread/approveGuardianDeniedAction", "Approve this retry in Codex Desktop."],
+]);
 const ACTION_METHODS = new Set([
   "item/commandExecution/requestApproval",
   "item/fileChange/requestApproval",
@@ -240,6 +255,7 @@ function createDesktopIpcActionFollower({
   const projectedLiveActiveTurnIdsByThreadId = new Map();
   const desktopLiveLifecycleByThreadId = new Map();
   const normalizedLiveIndexesByThreadId = new Map();
+  const normalizedReviewFingerprintsByThreadId = new Map();
   const staleYieldedThreadIds = new Set();
   const conversationProjector = createDesktopConversationProjector({ now });
   const pendingRoutesByRequestId = new Map();
@@ -301,6 +317,7 @@ function createDesktopIpcActionFollower({
     projectedLiveActiveTurnIdsByThreadId.delete(threadId);
     desktopLiveLifecycleByThreadId.delete(threadId);
     normalizedLiveIndexesByThreadId.delete(threadId);
+    normalizedReviewFingerprintsByThreadId.delete(threadId);
     conversationProjector.remove(threadId);
     queuedChangesByThreadId.delete(threadId);
     baselineRecoveryStateByThreadId.delete(threadId);
@@ -372,6 +389,14 @@ function createDesktopIpcActionFollower({
                 remodexActionSource: DESKTOP_IPC_ACTION_SOURCE,
               },
             }));
+            // Guardian reviews on normalized-only history turns never appear in
+            // canonical thread/read history, so drain their overlays here just
+            // like syncProjectedConversationState does; otherwise a thread that
+            // stays idle after opening never delivers them.
+            emitNormalizedReviewOverlays(
+              threadId,
+              normalizedLiveIndexesByThreadId.get(threadId)
+            );
             const output = conversationProjector.project(threadId, liveState, {
               includeAllActiveTurns: true,
             });
@@ -414,6 +439,27 @@ function createDesktopIpcActionFollower({
       }
     }
 
+    if (DESKTOP_OWNER_UNSUPPORTED_MUTATION_ERRORS.has(method)) {
+      const threadId = readThreadId(message?.params);
+      const mayBelongToDesktop = threadId
+        && !liveOwnerThreadIds.has(threadId)
+        && !isLocallyOwnedThread(threadId)
+        && (isDesktopRoutableThread(threadId)
+          || activeThreadIds.has(threadId)
+          || ownershipProbeDeadlinesByThreadId.has(threadId)
+          || pendingOwnershipProbeTokensByThreadId.has(threadId));
+      if (mayBelongToDesktop) {
+        sendApplicationResponse(JSON.stringify({
+          id: message?.id,
+          error: {
+            code: -32004,
+            message: DESKTOP_OWNER_UNSUPPORTED_MUTATION_ERRORS.get(method),
+          },
+        }));
+        return true;
+      }
+    }
+
     if (tryServeDesktopOwnedRead(message)) {
       return true;
     }
@@ -448,6 +494,7 @@ function createDesktopIpcActionFollower({
     projectedLiveActiveTurnIdsByThreadId.clear();
     desktopLiveLifecycleByThreadId.clear();
     normalizedLiveIndexesByThreadId.clear();
+    normalizedReviewFingerprintsByThreadId.clear();
     conversationProjector.reset();
     pendingRoutesByRequestId.clear();
     activeThreadIds.clear();
@@ -656,6 +703,7 @@ function createDesktopIpcActionFollower({
       onNormalizedHistoryIndexRebuilt(threadId);
     } else {
       normalizedLiveIndexesByThreadId.delete(threadId);
+      normalizedReviewFingerprintsByThreadId.delete(threadId);
     }
   }
 
@@ -690,6 +738,7 @@ function createDesktopIpcActionFollower({
     projectedLiveActiveTurnIdsByThreadId.clear();
     desktopLiveLifecycleByThreadId.clear();
     normalizedLiveIndexesByThreadId.clear();
+    normalizedReviewFingerprintsByThreadId.clear();
     recoveringThreadIds.clear();
     baselineRecoveryStateByThreadId.clear();
     queuedChangesByThreadId.clear();
@@ -730,6 +779,7 @@ function createDesktopIpcActionFollower({
     projectedLiveActiveTurnIdsByThreadId.delete(threadId);
     desktopLiveLifecycleByThreadId.delete(threadId);
     normalizedLiveIndexesByThreadId.delete(threadId);
+    normalizedReviewFingerprintsByThreadId.delete(threadId);
     conversationProjector.remove(threadId);
     queuedChangesByThreadId.delete(threadId);
     baselineRecoveryStateByThreadId.delete(threadId);
@@ -759,6 +809,7 @@ function createDesktopIpcActionFollower({
     projectedLiveActiveTurnIdsByThreadId.delete(threadId);
     desktopLiveLifecycleByThreadId.delete(threadId);
     normalizedLiveIndexesByThreadId.delete(threadId);
+    normalizedReviewFingerprintsByThreadId.delete(threadId);
     conversationProjector.remove(threadId);
     queuedChangesByThreadId.delete(threadId);
     baselineRecoveryStateByThreadId.delete(threadId);
@@ -1015,6 +1066,13 @@ function createDesktopIpcActionFollower({
     }
 
     rememberActiveThread(threadId);
+    if (method === "thread/goal/get") {
+      sendApplicationResponse(JSON.stringify({
+        id: message.id,
+        result: { goal: projectDesktopConversationStateToGoal(threadId, rawState) },
+      }));
+      return true;
+    }
     // Newer Litter snapshots keep materialized history in
     // turnHistory.history.entitiesByKey while leaving the legacy top-level
     // turns array empty or limited to only the current turn. The Desktop
@@ -1058,6 +1116,7 @@ function createDesktopIpcActionFollower({
           // echoing the raw Desktop conversationState alongside it doubled
           // heavy threads past the relay frame limit for nothing.
           thread,
+          ...(method === "thread/resume" ? { remodexDesktopIpcMirror: true } : {}),
         };
     if (!result) {
       return ownsDesktopCursor ? rejectDesktopTurnsCursor(message) : false;
@@ -1252,6 +1311,10 @@ function createDesktopIpcActionFollower({
           remodexActionSource: DESKTOP_IPC_ACTION_SOURCE,
         },
       }));
+      emitNormalizedReviewOverlays(
+        threadId,
+        normalizedLiveIndexesByThreadId.get(threadId)
+      );
       emitDesktopSnapshotLifecycleTransition(threadId, liveState);
       rememberDesktopLiveProjection(threadId, liveState);
       return;
@@ -1262,6 +1325,10 @@ function createDesktopIpcActionFollower({
       // baselines: preserve only turn lifecycle, then seed. Item diffs resume
       // on subsequent patches and cannot replay hundreds of old rows.
       emitDesktopSnapshotLifecycleTransition(threadId, liveState);
+      emitNormalizedReviewOverlays(
+        threadId,
+        normalizedLiveIndexesByThreadId.get(threadId)
+      );
       conversationProjector.seed(threadId, liveState);
       rememberDesktopLiveProjection(threadId, liveState);
       return;
@@ -1271,6 +1338,10 @@ function createDesktopIpcActionFollower({
       // is a source epoch change. Force a baseline + thread/replaced repair.
       conversationProjector.remove(threadId);
     }
+    emitNormalizedReviewOverlays(
+      threadId,
+      normalizedLiveIndexesByThreadId.get(threadId)
+    );
     const output = conversationProjector.project(threadId, liveState);
     if (resumedAfterStaleYield || output.type === "fullReplace" || output.type === "baseline") {
       // fullReplace: synthesized turn ids just became real, stale rows must go.
@@ -1303,6 +1374,66 @@ function createDesktopIpcActionFollower({
     rememberDesktopLiveProjection(threadId, liveState);
   }
 
+  function emitNormalizedReviewOverlays(threadId, index) {
+    if (!index || !Array.isArray(index.pendingReviewOverlays)) {
+      return;
+    }
+    const overlays = index.pendingReviewOverlays.splice(0);
+    const fingerprints = normalizedReviewFingerprintsByThreadId.get(threadId) || new Map();
+    for (const overlay of overlays) {
+      // Reviews on turns in the projected live tail may also be emitted by
+      // projector output; that duplication is intentional. The projector only
+      // re-emits items for active turns (and not after a silent reseed), so
+      // suppressing the overlay here would permanently drop reviews on
+      // completed tail turns. The phone upserts by reviewId, so duplicates
+      // cost one redundant notification and nothing else.
+      const item = overlay?.item;
+      const review = item?.review && typeof item.review === "object" ? item.review : item;
+      const reviewId = readString(item?.reviewId)
+        || readString(item?.id).replace(/^automatic-approval-review:/, "");
+      const status = readString(review?.status);
+      if (!reviewId || !status || !item?.action) {
+        continue;
+      }
+      const fingerprint = createHash("sha256")
+        .update(JSON.stringify({ status, item }))
+        .digest("hex");
+      if (fingerprints.get(reviewId) === fingerprint) {
+        continue;
+      }
+      // Refresh insertion order so the cache is a bounded per-thread LRU.
+      fingerprints.delete(reviewId);
+      fingerprints.set(reviewId, fingerprint);
+      while (fingerprints.size > MAX_NORMALIZED_REVIEW_FINGERPRINTS_PER_THREAD) {
+        const oldestReviewId = fingerprints.keys().next().value;
+        fingerprints.delete(oldestReviewId);
+      }
+      sendApplicationResponse(JSON.stringify({
+        method: normalizeToken(status) === "inprogress"
+          ? "item/autoApprovalReview/started"
+          : "item/autoApprovalReview/completed",
+        params: {
+          threadId,
+          turnId: overlay.turnId,
+          reviewId,
+          targetItemId: readString(item.targetItemId) || null,
+          startedAtMs: item.startedAtMs ?? null,
+          completedAtMs: item.completedAtMs ?? null,
+          decisionSource: readString(item.decisionSource)
+            || readString(item?.event?.decision_source)
+            || null,
+          review: cloneJSON(review),
+          action: cloneJSON(item.action),
+          remodexDesktopMirror: true,
+          remodexDesktopIpcMirror: true,
+          remodexGuardianRetrySupported: false,
+          remodexActionSource: DESKTOP_IPC_ACTION_SOURCE,
+        },
+      }));
+    }
+    normalizedReviewFingerprintsByThreadId.set(threadId, fingerprints);
+  }
+
   // Unopened chats only need run-state signals for the sidebar. Sending the
   // projector's full bootstrap here would replay every historical item from
   // every running Desktop chat onto the phone during a sidebar refresh.
@@ -1410,6 +1541,7 @@ function createDesktopIpcActionFollower({
       projectedLiveActiveTurnIdsByThreadId.delete(threadId);
       desktopLiveLifecycleByThreadId.delete(threadId);
       normalizedLiveIndexesByThreadId.delete(threadId);
+      normalizedReviewFingerprintsByThreadId.delete(threadId);
       conversationProjector.remove(threadId);
       syncProjectedActions(threadId, []);
     }
@@ -1531,7 +1663,14 @@ function createDesktopIpcActionFollower({
       .then(() => resolveFollowerRequestParams(route))
       .then(async (resolvedParams) => {
         if (route.method === "thread-follower-start-turn") {
-          await syncDesktopOwnerRuntimeSettings(route.threadId, resolvedParams.turnStartParams);
+          try {
+            await syncDesktopOwnerRuntimeSettings(route.threadId, resolvedParams.turnStartParams);
+          } catch (error) {
+            // The actual turn has not reached Desktop yet. Even if the settings
+            // request timed out after being applied, continuing through the local
+            // app-server is safe because there is no Desktop turn to duplicate.
+            throw markDeliveryFailureError(error);
+          }
         }
         return {
           resolvedParams,
@@ -2414,6 +2553,7 @@ function createNormalizedLiveIndex(state) {
     entryIndexByTurnId,
     turnIdByEntityKey,
     activeTurnIds: new Set(),
+    pendingReviewOverlays: [],
     hasHistoryOutsideRawTurns: Array.from(normalizedTurnIds).some(
       (turnId) => !rawTurnIds.has(turnId)
     ),
@@ -2423,6 +2563,14 @@ function createNormalizedLiveIndex(state) {
     if (turn && isActiveRawTurn(turn)) {
       index.activeTurnIds.add(entry.id);
     }
+    if (turn && entry.rawIndex == null) {
+      for (const item of Array.isArray(turn.items) ? turn.items : []) {
+        if (normalizeToken(item?.type) === "automaticapprovalreview") {
+          const overlay = { turnId: entry.id, item };
+          index.pendingReviewOverlays.push(overlay);
+        }
+      }
+    }
   }
   return index;
 }
@@ -2460,6 +2608,7 @@ function normalizedLiveIndexNeedsRebuild(change) {
 
 function refreshTouchedNormalizedActiveTurns(index, state, change) {
   const touchedTurnIds = new Set();
+  const touchedReviewTurnIds = new Set();
   for (const patch of Array.isArray(change?.patches) ? change.patches : []) {
     const path = Array.isArray(patch?.path) ? patch.path : [];
     if (path[0] === "turns" && Number.isInteger(path[1]) && path[2] === "status") {
@@ -2479,9 +2628,23 @@ function refreshTouchedNormalizedActiveTurns(index, state, change) {
         touchedTurnIds.add(turnId);
       }
     }
-  }
-  if (touchedTurnIds.size === 0) {
-    return;
+    if ((path[0] === "turnHistory" || path[0] === "turn_history")
+      && path[1] === "history"
+      && (path[2] === "entitiesByKey" || path[2] === "entities_by_key")
+      && path[4] === "items") {
+      const turnId = index.turnIdByEntityKey.get(readString(path[3]));
+      const entryIndex = turnId ? index.entryIndexByTurnId.get(turnId) : null;
+      const entry = entryIndex == null ? null : index.entries[entryIndex];
+      const turn = entry ? resolveIndexedTurn(state, entry) : null;
+      const item = Number.isInteger(path[5]) && Array.isArray(turn?.items)
+        ? turn.items[path[5]]
+        : null;
+      const isStructuralItemPatch = path.length <= 6 || path[6] === "type";
+      if (turnId && (isStructuralItemPatch
+        || normalizeToken(item?.type) === "automaticapprovalreview")) {
+        touchedReviewTurnIds.add(turnId);
+      }
+    }
   }
   for (const turnId of touchedTurnIds) {
     const entryIndex = index.entryIndexByTurnId.get(turnId);
@@ -2493,6 +2656,21 @@ function refreshTouchedNormalizedActiveTurns(index, state, change) {
       index.activeTurnIds.delete(turnId);
     }
   }
+  for (const turnId of touchedReviewTurnIds) {
+    const entryIndex = index.entryIndexByTurnId.get(turnId);
+    const entry = entryIndex == null ? null : index.entries[entryIndex];
+    const turn = entry ? resolveIndexedTurn(state, entry) : null;
+    if (!turn || entry?.rawIndex != null) {
+      continue;
+    }
+    for (const item of Array.isArray(turn.items) ? turn.items : []) {
+      if (normalizeToken(item?.type) !== "automaticapprovalreview") {
+        continue;
+      }
+      const overlay = { turnId, item };
+      index.pendingReviewOverlays.push(overlay);
+    }
+  }
 }
 
 function latestActiveRawTurn(state) {

package/src/desktop-ipc-conversation-adapter.js

@@ -220,6 +220,34 @@ function applyAppServerMessageToConversationState({
       conversation.updatedAt = now();
       return { threadId, changed: true };
     }
+    case "thread/goal/updated": {
+      const threadId = readThreadIdFromParams(message.params);
+      const goal = normalizeThreadGoal(message.params?.goal, threadId);
+      if (!threadId || !shouldOwnThread(threadId) || !goal) {
+        return null;
+      }
+      const conversation = ensureConversationInMap(conversations, threadId, { hostId, now });
+      if (goal.status === "complete") {
+        conversation.threadGoal = null;
+        conversation.completedThreadGoal = goal;
+      } else {
+        conversation.threadGoal = goal;
+        conversation.completedThreadGoal = null;
+      }
+      conversation.updatedAt = now();
+      return { threadId, changed: true };
+    }
+    case "thread/goal/cleared": {
+      const threadId = readThreadIdFromParams(message.params);
+      if (!threadId || !shouldOwnThread(threadId)) {
+        return null;
+      }
+      const conversation = ensureConversationInMap(conversations, threadId, { hostId, now });
+      conversation.threadGoal = null;
+      conversation.completedThreadGoal = null;
+      conversation.updatedAt = now();
+      return { threadId, changed: true };
+    }
     case "turn/started":
     case "turn/completed": {
       const threadId = readThreadIdFromParams(message.params);
@@ -322,6 +350,30 @@ function applyAppServerMessageToConversationState({
       conversation.updatedAt = now();
       return { threadId, changed: true };
     }
+    case "item/autoApprovalReview/started":
+    case "item/autoApprovalReview/completed": {
+      const threadId = readThreadIdFromParams(message.params);
+      if (!threadId || !shouldOwnThread(threadId)) {
+        return null;
+      }
+      const item = automaticApprovalReviewItemFromParams(message.params);
+      if (!item) {
+        return { threadId, changed: false };
+      }
+      const conversation = ensureConversationInMap(conversations, threadId, { hostId, now });
+      const turn = ensureTurn(conversation, resolveTurnIdForParams({
+        conversation,
+        params: message.params,
+        fallbackTurnIdsByThreadId,
+        now,
+      }), { now });
+      if (turn) {
+        upsertItem(turn, item);
+        turn.firstTurnWorkItemStartedAtMs = turn.firstTurnWorkItemStartedAtMs || now();
+      }
+      conversation.updatedAt = now();
+      return { threadId, changed: true };
+    }
     case "item/agentMessage/delta":
     case "item/plan/delta":
     case "item/reasoning/summaryTextDelta":
@@ -582,6 +634,7 @@ function buildConversationTurn(turn, {
   // Drop it here, position-independently, so no Desktop snapshot path leaks it
   // as a user bubble regardless of where the app-server placed it in the turn.
   builtTurn.items = builtTurn.items
+    .map(normalizeDesktopItemCompatibility)
     .map(sanitizeUserMessageItem)
     .filter(Boolean);
   // Hydrated turns from thread/read carry the prompt as an item with empty
@@ -731,6 +784,34 @@ function sanitizeUserMessageItem(item) {
   };
 }
 
+// Codex CLI 0.144.1 can omit receiverThreads from persisted collab tool calls,
+// while the matching Desktop renderer reads that collection without a fallback.
+// Keep the richer snapshots unchanged and synthesize lightweight references from
+// receiverThreadIds for older/CLI-owned rollouts so opening them cannot crash.
+function normalizeDesktopItemCompatibility(item) {
+  if (!item || typeof item !== "object" || normalizeToken(item.type) !== "collabagenttoolcall") {
+    return item;
+  }
+
+  const receiverThreads = Array.isArray(item.receiverThreads)
+    ? item.receiverThreads
+    : [];
+  const receiverThreadIds = Array.isArray(item.receiverThreadIds)
+    ? item.receiverThreadIds.map(readString).filter(Boolean)
+    : receiverThreads.map((entry) => readString(entry?.threadId)).filter(Boolean);
+  if (Array.isArray(item.receiverThreads) && Array.isArray(item.receiverThreadIds)) {
+    return item;
+  }
+
+  return {
+    ...item,
+    receiverThreadIds,
+    receiverThreads: Array.isArray(item.receiverThreads)
+      ? receiverThreads
+      : receiverThreadIds.map((threadId) => ({ threadId })),
+  };
+}
+
 function isInitialPromptUserMessageItem(turn, item) {
   if (!isUserMessageItem(item)) {
     return false;
@@ -908,8 +989,10 @@ function upsertItem(turn, item) {
   // user items too; no Codex UI renders it, so it must not reach the stream.
   // Also evict any copy that slipped into the state before this filter existed.
   const index = turn.items.findIndex((candidate) => readString(candidate?.id) === itemId);
-  const sanitizedItem = sanitizeUserMessageItem(item);
-  const existingItem = index >= 0 ? sanitizeUserMessageItem(turn.items[index]) : null;
+  const sanitizedItem = sanitizeUserMessageItem(normalizeDesktopItemCompatibility(item));
+  const existingItem = index >= 0
+    ? sanitizeUserMessageItem(normalizeDesktopItemCompatibility(turn.items[index]))
+    : null;
   if (!sanitizedItem) {
     if (index >= 0) {
       turn.items.splice(index, 1);
@@ -1099,10 +1182,62 @@ function readTurnIdFromTurn(turn) {
     || readString(turn?.turn_id);
 }
 
+function automaticApprovalReviewItemFromParams(params) {
+  const reviewId = readString(params?.reviewId);
+  const review = params?.review && typeof params.review === "object" ? params.review : null;
+  const status = readString(review?.status);
+  if (!reviewId || !status || !params?.action) {
+    return null;
+  }
+  return {
+    id: `automatic-approval-review:${reviewId}`,
+    type: "automaticApprovalReview",
+    reviewId,
+    targetItemId: readString(params?.targetItemId) || null,
+    status,
+    startedAtMs: params?.startedAtMs ?? null,
+    completedAtMs: params?.completedAtMs ?? null,
+    decisionSource: readString(params?.decisionSource) || null,
+    review: cloneJSON(review),
+    action: cloneJSON(params.action),
+    remodexGuardianRetrySupported: false,
+  };
+}
+
 function timestampSecondsToMs(value) {
   return Number.isFinite(value) && value > 0 ? Math.round(value * 1000) : 0;
 }
 
+function normalizeThreadGoal(value, fallbackThreadId = "") {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const threadId = readString(value.threadId) || readString(value.thread_id) || readString(fallbackThreadId);
+  const objective = readString(value.objective);
+  const statusByToken = {
+    active: "active",
+    paused: "paused",
+    blocked: "blocked",
+    usagelimited: "usageLimited",
+    budgetlimited: "budgetLimited",
+    complete: "complete",
+  };
+  const status = statusByToken[normalizeToken(value.status)] || "";
+  if (!threadId || !objective || !status) {
+    return null;
+  }
+  return {
+    threadId,
+    objective,
+    status,
+    tokenBudget: value.tokenBudget ?? value.token_budget ?? null,
+    tokensUsed: Number(value.tokensUsed ?? value.tokens_used) || 0,
+    timeUsedSeconds: Number(value.timeUsedSeconds ?? value.time_used_seconds) || 0,
+    createdAt: Number(value.createdAt ?? value.created_at) || 0,
+    updatedAt: Number(value.updatedAt ?? value.updated_at) || 0,
+  };
+}
+
 const REQUEST_METHODS_WITH_THREAD = new Set([
   "item/commandExecution/requestApproval",
   "item/fileChange/requestApproval",
@@ -1123,6 +1258,7 @@ module.exports = {
   createEmptyConversationState,
   ensureConversationInMap,
   mergeConversationTurnsFromThread,
+  normalizeThreadGoal,
   readThreadIdFromParams,
   readTurnIdFromParams,
   readTurnIdFromTurn,

package/src/desktop-ipc-conversation-projector.js

@@ -172,6 +172,10 @@ function projectDesktopConversationStateToThread(threadId, rawState, { now = ()
   return projectConversationState(threadId, rawState, { now }).thread;
 }
 
+function projectDesktopConversationStateToGoal(threadId, rawState) {
+  return latestThreadGoal(rawState, threadId);
+}
+
 function projectConversationState(threadId, rawState, {
   now = () => Date.now(),
   turnCache = null,
@@ -215,9 +219,12 @@ function projectConversationState(threadId, rawState, {
     turns,
   };
 
+  const goal = latestThreadGoal(rawState, threadId);
+
   return {
     thread,
     turns,
+    goal,
     activeTurnId,
     status: thread.status,
   };
@@ -332,6 +339,9 @@ function bootstrapNotifications(
   const notifications = includeThreadStarted && shouldEmitThreadStarted(projection.thread)
     ? [threadStartedNotification(projection.thread)]
     : [];
+  if (projection.goal) {
+    notifications.push(threadGoalUpdatedNotification(threadId, projection.goal));
+  }
   const activeTurns = includeAllActiveTurns
     ? projection.turns.filter((turn) => isActiveTurnStatus(turn.status))
     : [projection.activeTurnId
@@ -367,12 +377,26 @@ function diffProjections(threadId, previousProjection, nextProjection) {
   const notifications = [];
 
   notifications.push(...diffThreadMetadata(previousProjection.thread, nextProjection.thread));
+  notifications.push(...diffThreadGoal(threadId, previousProjection.goal, nextProjection.goal));
   notifications.push(...diffTurnLifecycle(threadId, previousProjection, nextProjection));
   notifications.push(...diffTurnItems(threadId, previousProjection, nextProjection));
 
   return notifications;
 }
 
+function diffThreadGoal(threadId, previousGoal, nextGoal) {
+  if (JSON.stringify(previousGoal || null) === JSON.stringify(nextGoal || null)) {
+    return [];
+  }
+  if (nextGoal) {
+    return [threadGoalUpdatedNotification(threadId, nextGoal)];
+  }
+  return [tagNotification({
+    method: "thread/goal/cleared",
+    params: { threadId },
+  })];
+}
+
 function diffThreadMetadata(previousThread, nextThread) {
   const notifications = [];
   const previousRuntimeRevision = Number(previousThread.runtimeSettingsRevision) || 0;
@@ -486,7 +510,11 @@ function diffTurnItems(threadId, previousProjection, nextProjection) {
         continue;
       }
       if (!isActiveTurn) {
-        notifications.push(itemCompletedNotification(threadId, nextTurn.id, nextItem));
+        if (isAutoApprovalReviewItem(nextItem) && !isTerminalItemState(nextItem)) {
+          notifications.push(itemStartedNotification(threadId, nextTurn.id, nextItem));
+        } else {
+          notifications.push(itemCompletedNotification(threadId, nextTurn.id, nextItem));
+        }
         continue;
       }
       notifications.push(...diffItem(threadId, nextTurn.id, previousItem, nextItem));
@@ -502,6 +530,11 @@ function diffItem(threadId, turnId, previousItem, nextItem) {
   // Previous text lengths come straight from the previous projection, which is
   // exactly what the per-thread snapshot map used to store.
   const snapshot = snapshotItem(previousItem);
+  if (isAutoApprovalReviewItem(nextItem)) {
+    return [isTerminalItemState(nextItem)
+      ? itemCompletedNotification(threadId, turnId, nextItem)
+      : itemStartedNotification(threadId, turnId, nextItem)];
+  }
   if (isAssistantMessageItem(nextItem)) {
     const previousText = assistantMessageText(previousItem);
     const nextText = assistantMessageText(nextItem);
@@ -644,6 +677,17 @@ function turnStartedNotification(threadId, turn) {
   });
 }
 
+function threadGoalUpdatedNotification(threadId, goal) {
+  return tagNotification({
+    method: "thread/goal/updated",
+    params: {
+      threadId,
+      turnId: null,
+      goal: cloneJSON(goal),
+    },
+  });
+}
+
 function turnCompletedNotification(threadId, turn) {
   return tagNotification({
     method: "turn/completed",
@@ -658,6 +702,9 @@ function turnCompletedNotification(threadId, turn) {
 }
 
 function itemStartedNotification(threadId, turnId, item) {
+  if (isAutoApprovalReviewItem(item)) {
+    return autoApprovalReviewNotification("item/autoApprovalReview/started", threadId, turnId, item);
+  }
   return tagNotification({
     method: "item/started",
     params: {
@@ -670,6 +717,9 @@ function itemStartedNotification(threadId, turnId, item) {
 }
 
 function itemCompletedNotification(threadId, turnId, item) {
+  if (isAutoApprovalReviewItem(item)) {
+    return autoApprovalReviewNotification("item/autoApprovalReview/completed", threadId, turnId, item);
+  }
   return tagNotification({
     method: "item/completed",
     params: {
@@ -681,6 +731,21 @@ function itemCompletedNotification(threadId, turnId, item) {
   });
 }
 
+// Guardian reviews have no ThreadItem variant in the app-server protocol; the
+// live wire shape is the dedicated `item/autoApprovalReview/*` notification.
+// Re-emit that shape so mobile reuses one decoder for owned and mirrored threads.
+function autoApprovalReviewNotification(method, threadId, turnId, item) {
+  const { type, id, status, ...payload } = item;
+  return tagNotification({
+    method,
+    params: {
+      threadId,
+      turnId,
+      ...cloneJSON(payload),
+    },
+  });
+}
+
 function deltaNotification(method, threadId, turnId, itemId, delta, extraParams = {}) {
   return tagNotification({
     method,
@@ -994,6 +1059,9 @@ function sanitizeUserInputEntries(entries) {
 // Keep the original type as metadata, but emit the generic shape iOS already decodes.
 // Returns null when the item has nothing user-visible left after sanitizing.
 function projectItemForMobile(item, itemType = normalizeToken(item?.type)) {
+  if (itemType === "automaticapprovalreview") {
+    return projectAutoApprovalReviewItem(item);
+  }
   if (itemType === "usermessage") {
     const visibleContent = sanitizeUserInputEntries(
       Array.isArray(item?.content) ? item.content : []
@@ -1024,8 +1092,53 @@ function projectItemForMobile(item, itemType = normalizeToken(item?.type)) {
   return projected;
 }
 
+const AUTO_APPROVAL_REVIEW_ITEM_ID_PREFIX = "automatic-approval-review:";
+
+function isAutoApprovalReviewItem(item) {
+  return normalizeToken(item?.type) === "automaticapprovalreview";
+}
+
+// Desktop flattens `item/autoApprovalReview/*` notifications into synthetic
+// `automaticApprovalReview` turn items. Normalize back to the app-server
+// notification shape; keep top-level `status` for lifecycle checks.
+function projectAutoApprovalReviewItem(item) {
+  const rawId = itemIdOf(item);
+  if (!rawId) {
+    return null;
+  }
+  const review = item?.review && typeof item.review === "object" ? item.review : item;
+  const status = readString(review.status);
+  if (!status) {
+    return null;
+  }
+  return {
+    type: "automaticApprovalReview",
+    id: rawId,
+    reviewId: readString(item.reviewId)
+      || (rawId.startsWith(AUTO_APPROVAL_REVIEW_ITEM_ID_PREFIX)
+        ? rawId.slice(AUTO_APPROVAL_REVIEW_ITEM_ID_PREFIX.length)
+        : rawId),
+    targetItemId: readString(item.targetItemId) || null,
+    status,
+    startedAtMs: item.startedAtMs ?? null,
+    completedAtMs: item.completedAtMs ?? null,
+    decisionSource: readString(item.decisionSource)
+      || readString(item?.event?.decision_source)
+      || null,
+    review: {
+      status,
+      riskLevel: readString(review.riskLevel) || null,
+      userAuthorization: readString(review.userAuthorization) || null,
+      rationale: readString(review.rationale) || null,
+    },
+    action: cloneJSON(item.action ?? null),
+    ...MIRROR_TAG,
+  };
+}
+
 function isSupportedItemType(type) {
   return type === "usermessage"
+    || type === "automaticapprovalreview"
     || type === "hookprompt"
     || type === "agentmessage"
     || type === "assistantmessage"
@@ -1161,9 +1274,42 @@ function normalizeTimestamp(value) {
   return Number.isFinite(numeric) && numeric > 0 ? numeric : 0;
 }
 
+function latestThreadGoal(rawState, threadId) {
+  const candidates = [rawState?.threadGoal, rawState?.completedThreadGoal]
+    .map((goal) => normalizeProjectedThreadGoal(goal, threadId))
+    .filter(Boolean);
+  return candidates.sort((left, right) => right.updatedAt - left.updatedAt)[0] || null;
+}
+
+function normalizeProjectedThreadGoal(value, fallbackThreadId) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const statusByToken = {
+    active: "active",
+    paused: "paused",
+    blocked: "blocked",
+    usagelimited: "usageLimited",
+    budgetlimited: "budgetLimited",
+    complete: "complete",
+  };
+  const goal = {
+    threadId: readString(value.threadId) || readString(value.thread_id) || fallbackThreadId,
+    objective: readString(value.objective),
+    status: statusByToken[normalizeToken(value.status)] || "",
+    tokenBudget: value.tokenBudget ?? value.token_budget ?? null,
+    tokensUsed: Number(value.tokensUsed ?? value.tokens_used) || 0,
+    timeUsedSeconds: Number(value.timeUsedSeconds ?? value.time_used_seconds) || 0,
+    createdAt: Number(value.createdAt ?? value.created_at) || 0,
+    updatedAt: Number(value.updatedAt ?? value.updated_at) || 0,
+  };
+  return goal.threadId && goal.objective && goal.status ? goal : null;
+}
+
 module.exports = {
   createDesktopConversationProjector,
   desktopTurnsShareLogicalIdentity,
   matchDesktopTurnIdentityContinuities,
+  projectDesktopConversationStateToGoal,
   projectDesktopConversationStateToThread,
 };

package/src/push-notification-tracker.js

@@ -4,14 +4,29 @@
 // Exports: createPushNotificationTracker
 // Depends on: ./push-notification-completion-dedupe
 
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
 const {
   createPushNotificationCompletionDedupe,
 } = require("./push-notification-completion-dedupe");
 
+const DEFAULT_GOAL_PUSH_STATE_PATH = path.join(os.homedir(), ".remodex", "goal-push-state.json");
+
 const DEFAULT_PREVIEW_MAX_CHARS = 160;
 const MAX_THREAD_TITLE_ENTRIES = 200;
 const MAX_TURN_STATE_ENTRIES = 500;
 const MAX_THREAD_ID_BY_TURN_ENTRIES = 500;
+const MAX_GOAL_STATUS_ENTRIES = 500;
+
+// Goal states worth waking the phone for: terminal or needs-user-attention.
+const GOAL_PUSH_BODIES = new Map([
+  ["complete", "Goal complete"],
+  ["blocked", "Goal blocked — Codex needs your input"],
+  ["usageLimited", "Goal stopped — usage limit reached"],
+  ["budgetLimited", "Goal stopped — token budget reached"],
+]);
 
 function createPushNotificationTracker({
   sessionId,
@@ -19,10 +34,14 @@ function createPushNotificationTracker({
   previewMaxChars = DEFAULT_PREVIEW_MAX_CHARS,
   logPrefix = "[remodex]",
   now = () => Date.now(),
+  goalPushStatePath = DEFAULT_GOAL_PUSH_STATE_PATH,
 } = {}) {
   const threadTitleById = new Map();
   const threadIdByTurnId = new Map();
   const turnStateByKey = new Map();
+  // Persisted across bridge restarts so goal transitions that happened while the
+  // bridge was down still notify on the first post-restart snapshot.
+  const goalStatusByThreadId = loadGoalPushState(goalPushStatePath, logPrefix);
   const completionDedupe = createPushNotificationCompletionDedupe({ now });
 
   // ─── ENTRY POINT ─────────────────────────────────────────────
@@ -33,6 +52,18 @@ function createPushNotificationTracker({
       return;
     }
 
+    if (message.method === "thread/goal/updated") {
+      void handleGoalUpdated(message);
+      return;
+    }
+
+    if (message.method === "thread/goal/cleared") {
+      if (message.threadId && goalStatusByThreadId.delete(message.threadId)) {
+        saveGoalPushState(goalPushStatePath, goalStatusByThreadId, logPrefix);
+      }
+      return;
+    }
+
     rememberMessageContext(message);
     clearFallbackSuppressionForNewRun(message);
 
@@ -73,6 +104,59 @@ function createPushNotificationTracker({
     }
   }
 
+  // Pushes goal lifecycle transitions into terminal/attention states so hours-long
+  // background goals still reach the user. Resume snapshots (first observation of a
+  // status) never notify; only live status changes do.
+  async function handleGoalUpdated({ threadId, params }) {
+    const goal = objectValue(params?.goal);
+    const status = readString(goal?.status);
+    const resolvedThreadId = threadId || readString(goal?.threadId);
+    if (!resolvedThreadId || !status) {
+      return;
+    }
+
+    const previousSnapshot = normalizeGoalPushSnapshot(goalStatusByThreadId.get(resolvedThreadId));
+    const nextSnapshot = {
+      status,
+      updatedAt: goal?.updatedAt ?? goal?.updated_at ?? null,
+    };
+    if (!goalStatusByThreadId.has(resolvedThreadId) && goalStatusByThreadId.size >= MAX_GOAL_STATUS_ENTRIES) {
+      const oldest = goalStatusByThreadId.keys().next().value;
+      goalStatusByThreadId.delete(oldest);
+    }
+    const isFirstObservation = previousSnapshot == null;
+    const isDuplicate = previousSnapshot?.status === nextSnapshot.status
+      && previousSnapshot?.updatedAt === nextSnapshot.updatedAt;
+    const body = GOAL_PUSH_BODIES.get(status);
+    if (isFirstObservation || isDuplicate || !body || !pushServiceClient?.hasConfiguredBaseUrl) {
+      if (!isDuplicate) {
+        goalStatusByThreadId.set(resolvedThreadId, nextSnapshot);
+        saveGoalPushState(goalPushStatePath, goalStatusByThreadId, logPrefix);
+      }
+      return;
+    }
+
+    const title = normalizePreviewText(threadTitleById.get(resolvedThreadId)) || "New Thread";
+    // The goal objective intentionally stays out of push payloads and logs.
+    try {
+      await pushServiceClient.notifyCompletion({
+        threadId: resolvedThreadId,
+        turnId: null,
+        result: status === "complete" ? "completed" : "failed",
+        title,
+        body,
+        // updatedAt keeps repeated legitimate transitions (blocked -> active -> blocked) notifiable.
+        dedupeKey: [sessionId || "", resolvedThreadId, "goal", status, goal?.updatedAt ?? ""].join("|"),
+      });
+      // Commit the dedupe cursor only after delivery succeeds so a repeated
+      // app-server snapshot can retry a transient push outage.
+      goalStatusByThreadId.set(resolvedThreadId, nextSnapshot);
+      saveGoalPushState(goalPushStatePath, goalStatusByThreadId, logPrefix);
+    } catch (error) {
+      console.error(`${logPrefix} goal push notify failed: ${error.message}`);
+    }
+  }
+
   // Remembers thread/turn linkage before the terminal event arrives on a different payload shape.
   function rememberMessageContext({ threadId, turnId, params, eventObject }) {
     if (threadId && turnId) {
@@ -273,6 +357,56 @@ function createPushNotificationTracker({
   };
 }
 
+// Best-effort disk persistence for goal statuses; failures must never break the bridge.
+function loadGoalPushState(filePath, logPrefix) {
+  if (!filePath) {
+    return new Map();
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return new Map();
+    }
+    const entries = Object.entries(parsed)
+      .map(([threadId, snapshot]) => [threadId, normalizeGoalPushSnapshot(snapshot)])
+      .filter(([threadId, snapshot]) => typeof threadId === "string" && snapshot != null)
+      .slice(-MAX_GOAL_STATUS_ENTRIES);
+    return new Map(entries);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      console.error(`${logPrefix} failed to load goal push state: ${error.message}`);
+    }
+    return new Map();
+  }
+}
+
+function normalizeGoalPushSnapshot(value) {
+  if (typeof value === "string") {
+    return { status: value, updatedAt: null };
+  }
+  if (!value || typeof value !== "object" || typeof value.status !== "string") {
+    return null;
+  }
+  return {
+    status: value.status,
+    updatedAt: value.updatedAt ?? null,
+  };
+}
+
+function saveGoalPushState(filePath, goalStatusByThreadId, logPrefix) {
+  if (!filePath) {
+    return;
+  }
+
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(Object.fromEntries(goalStatusByThreadId)));
+  } catch (error) {
+    console.error(`${logPrefix} failed to save goal push state: ${error.message}`);
+  }
+}
+
 // Normalizes the message envelope once so downstream helpers can share the same parsed view.
 function parseOutboundMessage(rawMessage, parsedMessage = null) {
   const parsed = parsedMessage ?? safeParseJSON(rawMessage);

package/src/rollout-live-mirror.js

@@ -799,6 +799,26 @@ function synthesizeNotificationsFromRolloutEntry(entry, state, { nowMs = Date.no
     const payload = entry.payload || {};
     const eventType = readString(payload.type);
 
+    if (eventType === "thread_goal_updated") {
+      const goal = payload.goal && typeof payload.goal === "object" ? payload.goal : null;
+      const threadId = readString(payload.threadId) || readString(goal?.threadId) || state.threadId;
+      if (!goal || !threadId) {
+        return [];
+      }
+      return [createNotification("thread/goal/updated", {
+        threadId,
+        turnId: readString(payload.turnId) || readString(payload.turn_id) || null,
+        goal,
+      })];
+    }
+
+    if (eventType === "thread_goal_cleared") {
+      const threadId = readString(payload.threadId) || readString(payload.thread_id) || state.threadId;
+      return threadId
+        ? [createNotification("thread/goal/cleared", { threadId })]
+        : [];
+    }
+
     if (eventType === "task_started") {
       notifications.push(...finalizePendingSyntheticTerminal(state));
       const explicitTurnId = readString(payload.turn_id) || readString(payload.turnId);