@makerbi/remodex 2.4.0 → 3.1.0

package/src/rollout-watch.js

@@ -20,6 +20,13 @@ const DEFAULT_CONTEXT_READ_SCAN_BYTES = 512 * 1024;
 const DEFAULT_CONTEXT_READ_CANDIDATE_LIMIT = 128;
 const DEFAULT_RECENT_ROLLOUT_CANDIDATE_LIMIT = 24;
 const DEFAULT_RECENT_ROLLOUT_LOOKBACK_MS = 15 * 60 * 1000;
+const ROLLOUT_CANDIDATE_CACHE_TTL_MS = 2_000;
+const ROLLOUT_THREAD_POSITIVE_CACHE_TTL_MS = 2_000;
+const ROLLOUT_THREAD_NEGATIVE_CACHE_TTL_MS = 1_500;
+const ROLLOUT_LOOKUP_CACHE_MAX_ROOTS = 32;
+const ROLLOUT_THREAD_MEMO_MAX_SIZE = 2_000;
+const ROLLOUT_THREAD_CONTENT_CACHE_MAX_SIZE = 4_000;
+const rolloutLookupCachesByFsModule = new WeakMap();
 
 // Polls one rollout file until it materializes and then reports size growth.
 function createThreadRolloutActivityWatcher({
@@ -350,12 +357,35 @@ function findRecentRolloutFileForContextRead(
     threadLookupScanBytes = DEFAULT_THREAD_LOOKUP_SCAN_BYTES,
   } = {}
 ) {
+  const currentTime = now();
+  const cache = rolloutLookupCacheForFsModule(fsModule);
+  const threadMemoKey = threadId && !turnId
+    ? rolloutThreadMemoKey(root, threadId)
+    : "";
+  if (threadMemoKey) {
+    const positive = cache.positiveThreadPaths.get(threadMemoKey);
+    if (positive) {
+      if (positive.expiresAt > currentTime && fsModule.existsSync(positive.filePath)) {
+        return positive.filePath;
+      }
+      cache.positiveThreadPaths.delete(threadMemoKey);
+    }
+
+    const negativeExpiresAt = cache.negativeThreadLookups.get(threadMemoKey) || 0;
+    if (negativeExpiresAt > currentTime) {
+      return null;
+    }
+    cache.negativeThreadLookups.delete(threadMemoKey);
+  }
+
   const candidates = collectRecentRolloutFiles(root, {
     fsModule,
     candidateLimit,
     modifiedAfterMs: 0,
+    now,
   });
   if (candidates.length === 0) {
+    rememberNegativeThreadLookup(cache, threadMemoKey, currentTime);
     return null;
   }
 
@@ -373,8 +403,10 @@ function findRecentRolloutFileForContextRead(
   if (threadId) {
     const threadScopedRollout = findPreferredRolloutFileForThread(root, candidates, threadId, {
       fsModule,
+      now,
     });
     if (threadScopedRollout) {
+      rememberPositiveThreadPath(cache, threadMemoKey, threadScopedRollout, currentTime);
       return threadScopedRollout;
     }
 
@@ -383,23 +415,33 @@ function findRecentRolloutFileForContextRead(
         fsModule,
         scanBytes: threadLookupScanBytes,
       })) {
+        rememberPositiveThreadPath(cache, threadMemoKey, candidate.filePath, currentTime);
         return candidate.filePath;
       }
     }
   }
 
+  rememberNegativeThreadLookup(cache, threadMemoKey, currentTime);
   return null;
 }
 
 // Keeps the fast "recent files first" path, but falls back to a full-tree scan
 // so older valid thread rollouts still recover after many newer sessions exist.
-function findPreferredRolloutFileForThread(root, candidates, threadId, { fsModule = fs } = {}) {
+function findPreferredRolloutFileForThread(
+  root,
+  candidates,
+  threadId,
+  {
+    fsModule = fs,
+    now = () => Date.now(),
+  } = {}
+) {
   const recentMatch = findMostRecentRolloutFileForThread(candidates, threadId);
   if (recentMatch) {
     return recentMatch;
   }
 
-  return findNewestRolloutFileForThread(root, threadId, { fsModule });
+  return findNewestRolloutFileForThread(root, threadId, { fsModule, now });
 }
 
 // Prefers the newest filename-scoped rollout for a thread instead of the first
@@ -413,45 +455,29 @@ function findMostRecentRolloutFileForThread(candidates, threadId) {
   return match?.filePath || null;
 }
 
-// Scans the whole sessions tree only when the recent candidate window missed the
+// Uses the complete sorted candidate set when the recent slice missed the
 // thread, still preferring the newest matching rollout instead of the first hit.
-function findNewestRolloutFileForThread(root, threadId, { fsModule = fs } = {}) {
-  if (!threadId || !fsModule.existsSync(root)) {
+function findNewestRolloutFileForThread(
+  root,
+  threadId,
+  {
+    fsModule = fs,
+    now = () => Date.now(),
+  } = {}
+) {
+  if (!threadId) {
     return null;
   }
 
-  const stack = [root];
-  let newestMatch = null;
-
-  while (stack.length > 0) {
-    const current = stack.pop();
-    const entries = fsModule.readdirSync(current, { withFileTypes: true });
-
-    for (const entry of entries) {
-      const fullPath = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(fullPath);
-        continue;
-      }
-
-      if (!entry.isFile()
-        || !entry.name.startsWith("rollout-")
-        || !entry.name.endsWith(".jsonl")
-        || !entry.name.includes(threadId)) {
-        continue;
-      }
-
-      const candidate = {
-        filePath: fullPath,
-        mtimeMs: fsModule.statSync(fullPath).mtimeMs,
-      };
-      if (!newestMatch || compareRolloutFileOrder(candidate, newestMatch) < 0) {
-        newestMatch = candidate;
-      }
-    }
-  }
-
-  return newestMatch?.filePath || null;
+  return findMostRecentRolloutFileForThread(
+    collectRecentRolloutFiles(root, {
+      fsModule,
+      candidateLimit: Number.POSITIVE_INFINITY,
+      modifiedAfterMs: 0,
+      now,
+    }),
+    threadId
+  );
 }
 
 function collectRecentRolloutFiles(
@@ -460,12 +486,33 @@ function collectRecentRolloutFiles(
     fsModule = fs,
     candidateLimit = DEFAULT_RECENT_ROLLOUT_CANDIDATE_LIMIT,
     modifiedAfterMs = 0,
+    now = () => Date.now(),
   } = {}
 ) {
+  const cache = rolloutLookupCacheForFsModule(fsModule);
+  const currentTime = now();
+  const cached = cache.candidatesByRoot.get(root);
+  let candidates = cached?.candidates;
+  if (!cached || currentTime - cached.createdAt >= ROLLOUT_CANDIDATE_CACHE_TTL_MS) {
+    candidates = scanRolloutFiles(root, fsModule);
+    cache.candidatesByRoot.delete(root);
+    cache.candidatesByRoot.set(root, {
+      candidates,
+      createdAt: currentTime,
+    });
+    evictOldestCacheEntries(cache.candidatesByRoot, ROLLOUT_LOOKUP_CACHE_MAX_ROOTS);
+  }
+
+  const filtered = modifiedAfterMs > 0
+    ? candidates.filter(({ mtimeMs }) => mtimeMs >= modifiedAfterMs)
+    : candidates;
+  return filtered.slice(0, candidateLimit);
+}
+
+function scanRolloutFiles(root, fsModule) {
   if (!fsModule.existsSync(root)) {
     return [];
   }
-
   const stack = [root];
   const candidates = [];
 
@@ -487,10 +534,6 @@ function collectRecentRolloutFiles(
       }
 
       const stat = fsModule.statSync(fullPath);
-      if (modifiedAfterMs > 0 && stat.mtimeMs < modifiedAfterMs) {
-        continue;
-      }
-
       candidates.push({
         filePath: fullPath,
         mtimeMs: stat.mtimeMs,
@@ -503,17 +546,7 @@ function collectRecentRolloutFiles(
       || path.basename(rhs.filePath).localeCompare(path.basename(lhs.filePath))
       || rhs.filePath.localeCompare(lhs.filePath)
   );
-  return candidates.slice(0, candidateLimit);
-}
-
-// Keeps rollout selection deterministic when filesystem timestamp resolution
-// reports equal mtimes for several rollout candidates.
-function compareRolloutFileOrder(lhs, rhs) {
-  if (lhs.mtimeMs !== rhs.mtimeMs) {
-    return rhs.mtimeMs - lhs.mtimeMs;
-  }
-
-  return rhs.filePath.localeCompare(lhs.filePath);
+  return candidates;
 }
 
 function rolloutFileContainsTurnId(
@@ -555,6 +588,11 @@ function rolloutFileContainsThreadId(
   }
 
   const stat = fsModule.statSync(filePath);
+  const cache = rolloutLookupCacheForFsModule(fsModule);
+  const cacheKey = `${filePath}\0${threadId}\0${stat.size}\0${scanBytes}`;
+  if (cache.threadContentMatches.has(cacheKey)) {
+    return cache.threadContentMatches.get(cacheKey);
+  }
   const chunk = readFileSlice(
     filePath,
     Math.max(0, stat.size - Math.min(stat.size, scanBytes)),
@@ -562,15 +600,98 @@ function rolloutFileContainsThreadId(
     fsModule
   );
   if (!chunk) {
+    rememberThreadContentMatch(cache, cacheKey, false);
     return false;
   }
 
-  return (
+  const matches = (
     chunk.includes(`"thread_id":"${threadId}"`)
       || chunk.includes(`"threadId":"${threadId}"`)
       || chunk.includes(`"conversation_id":"${threadId}"`)
       || chunk.includes(`"conversationId":"${threadId}"`)
   );
+  rememberThreadContentMatch(cache, cacheKey, matches);
+  return matches;
+}
+
+function rolloutLookupCacheForFsModule(fsModule) {
+  let cache = rolloutLookupCachesByFsModule.get(fsModule);
+  if (!cache) {
+    cache = {
+      candidatesByRoot: new Map(),
+      positiveThreadPaths: new Map(),
+      negativeThreadLookups: new Map(),
+      threadContentMatches: new Map(),
+    };
+    rolloutLookupCachesByFsModule.set(fsModule, cache);
+  }
+  return cache;
+}
+
+function rolloutThreadMemoKey(root, threadId) {
+  return `${root}\0${threadId}`;
+}
+
+function rememberPositiveThreadPath(cache, memoKey, filePath, currentTime) {
+  if (!memoKey) {
+    return;
+  }
+  cache.negativeThreadLookups.delete(memoKey);
+  cache.positiveThreadPaths.delete(memoKey);
+  cache.positiveThreadPaths.set(memoKey, {
+    filePath,
+    expiresAt: currentTime + ROLLOUT_THREAD_POSITIVE_CACHE_TTL_MS,
+  });
+  evictOldestCacheEntries(cache.positiveThreadPaths, ROLLOUT_THREAD_MEMO_MAX_SIZE);
+}
+
+function rememberNegativeThreadLookup(cache, memoKey, currentTime) {
+  if (!memoKey) {
+    return;
+  }
+  cache.negativeThreadLookups.delete(memoKey);
+  cache.negativeThreadLookups.set(
+    memoKey,
+    currentTime + ROLLOUT_THREAD_NEGATIVE_CACHE_TTL_MS
+  );
+  evictOldestCacheEntries(cache.negativeThreadLookups, ROLLOUT_THREAD_MEMO_MAX_SIZE);
+}
+
+function rememberThreadContentMatch(cache, cacheKey, matches) {
+  cache.threadContentMatches.set(cacheKey, matches);
+  evictOldestCacheEntries(
+    cache.threadContentMatches,
+    ROLLOUT_THREAD_CONTENT_CACHE_MAX_SIZE
+  );
+}
+
+function evictOldestCacheEntries(cache, maxSize) {
+  while (cache.size > maxSize) {
+    cache.delete(cache.keys().next().value);
+  }
+}
+
+function invalidateRolloutLookupCache({
+  root = "",
+  threadId = "",
+  fsModule = fs,
+} = {}) {
+  const cache = rolloutLookupCachesByFsModule.get(fsModule);
+  if (!cache) {
+    return;
+  }
+  if (!root) {
+    rolloutLookupCachesByFsModule.delete(fsModule);
+    return;
+  }
+
+  cache.candidatesByRoot.delete(root);
+  if (!threadId) {
+    return;
+  }
+  const memoKey = rolloutThreadMemoKey(root, threadId);
+  cache.positiveThreadPaths.delete(memoKey);
+  cache.negativeThreadLookups.delete(memoKey);
 }
 
 function formatRolloutLine(rawLine) {
@@ -845,4 +966,5 @@ module.exports = {
   resolveSessionsRoot,
   findRolloutFileForThread,
   findRecentRolloutFileForContextRead,
+  invalidateRolloutLookupCache,
 };

package/src/session-jsonl-history.js

@@ -4,6 +4,10 @@
 
 const fs = require("fs");
 const { buildApplyPatchFileChangeItem } = require("./apply-patch-changes");
+const {
+  expandExecWrapperToolCall,
+  isOrchestrationWaitCall,
+} = require("./codex-tool-wrapper");
 const { terminalEventClosesTrackedTurn } = require("./rollout-turn-semantics");
 const {
   buildRemodexSourceItemKey,
@@ -166,7 +170,7 @@ function readSessionJsonlMetadataFromFile(filePath, {
   metadataHeadBytes = DEFAULT_SESSION_JSONL_METADATA_HEAD_BYTES,
 } = {}) {
   if (!filePath) {
-    return { threadId: "", cwd: "" };
+    return emptySessionJsonlMetadata();
   }
   if (!supportsBoundedSessionJsonlReads(fsModule)) {
     return parseSessionJsonlMetadata(fsModule.readFileSync(filePath, "utf8"));
@@ -175,7 +179,7 @@ function readSessionJsonlMetadataFromFile(filePath, {
   const stat = fsModule.statSync(filePath);
   const snapshotSize = Math.max(0, Number(stat?.size) || 0);
   if (snapshotSize === 0) {
-    return { threadId: "", cwd: "" };
+    return emptySessionJsonlMetadata();
   }
   const fileHandle = fsModule.openSync(filePath, "r");
   try {
@@ -186,12 +190,23 @@ function readSessionJsonlMetadataFromFile(filePath, {
       fsModule
     );
     const metadata = parseSessionJsonlInitialMetadata(head.toString("utf8"));
-    return { threadId: metadata.threadId, cwd: metadata.cwd };
+    return {
+      threadId: metadata.threadId,
+      cwd: metadata.cwd,
+      forkedFromId: metadata.forkedFromId,
+      threadSource: metadata.threadSource,
+    };
   } finally {
     fsModule.closeSync(fileHandle);
   }
 }
 
+// Every exit path of readSessionJsonlMetadataFromFile returns this shape so callers
+// can read provenance without knowing which branch produced the result.
+function emptySessionJsonlMetadata() {
+  return { threadId: "", cwd: "", forkedFromId: "", threadSource: "" };
+}
+
 function supportsBoundedSessionJsonlReads(fsModule) {
   return typeof fsModule?.statSync === "function"
     && typeof fsModule?.openSync === "function"
@@ -287,6 +302,11 @@ function parseSessionJsonlInitialMetadata(content) {
   let threadId = "";
   let cwd = "";
   let timeZone = "";
+  // Provenance app-server keeps in the rollout but leaves null on thread/list
+  // rows: without it a forked automation thread is indistinguishable from the
+  // origin it copied its name and preview from.
+  let forkedFromId = "";
+  let threadSource = "";
   const raw = String(content || "");
   let lineStart = 0;
   while (lineStart < raw.length) {
@@ -314,18 +334,24 @@ function parseSessionJsonlInitialMetadata(content) {
       timeZone = normalizeString(payload?.timezone)
         || normalizeString(payload?.timeZone)
         || normalizeString(payload?.time_zone);
+      forkedFromId = normalizeString(payload?.forked_from_id)
+        || normalizeString(payload?.forkedFromId);
+      threadSource = normalizeString(payload?.thread_source)
+        || normalizeString(payload?.threadSource);
       break;
     } catch {
       // Metadata is expected at the head; an incomplete oversized line is not trusted.
     }
   }
-  return { threadId, cwd, timeZone };
+  return { threadId, cwd, timeZone, forkedFromId, threadSource };
 }
 
 // Extracts thread-level context that app-server history can omit for desktop-origin runs.
 function parseSessionJsonlMetadata(content) {
   let threadId = "";
   let cwd = "";
+  let forkedFromId = "";
+  let threadSource = "";
 
   const raw = String(content || "");
   let lineStart = 0;
@@ -358,13 +384,17 @@ function parseSessionJsonlMetadata(content) {
     cwd ||= normalizeString(payload?.cwd)
       || normalizeString(payload?.current_working_directory)
       || normalizeString(payload?.working_directory);
+    forkedFromId ||= normalizeString(payload?.forked_from_id)
+      || normalizeString(payload?.forkedFromId);
+    threadSource ||= normalizeString(payload?.thread_source)
+      || normalizeString(payload?.threadSource);
 
     if (threadId && cwd) {
       break;
     }
   }
 
-  return { threadId, cwd };
+  return { threadId, cwd, forkedFromId, threadSource };
 }
 
 function parseSessionJsonlTurns(content, {
@@ -559,36 +589,39 @@ function parseSessionJsonlTurns(content, {
       if (!payload) {
         continue;
       }
-      rememberToolCallForHistory(payload, toolCallsByCallId);
-      if (shouldSkipResponseItemForHistory(payload, skippedCallIds)) {
-        continue;
-      }
-      const turn = ensureTurn(
-        turns,
-        turnsById,
-        responseItemTurnId(payload) || activeTurnId || `turn-line-${sourceLineNumber}`,
-        sessionThreadId,
-        entry.timestamp
-      );
-      applyHistoryTimeZone(turn, sessionTimeZone);
-      const item = normalizeResponseItemForHistory(payload, sourceLineNumber, {
-        cwd: sessionCwd,
-        toolCallsByCallId,
-      });
-      if (item) {
-        if (shouldSkipDuplicateProposedPlanMessage(turn, item)) {
+      const projectedPayloads = expandExecWrapperToolCall(payload);
+      for (const projectedPayload of projectedPayloads) {
+        rememberToolCallForHistory(projectedPayload, toolCallsByCallId);
+        if (shouldSkipResponseItemForHistory(projectedPayload, skippedCallIds)) {
           continue;
         }
-        const itemTimestamp = historyItemTimestamp(item, entry.timestamp);
-        if (itemTimestamp && !item.createdAt) {
-          item.createdAt = itemTimestamp;
-        }
-        if (itemTimestamp && !item.timestamp) {
-          item.timestamp = itemTimestamp;
+        const turn = ensureTurn(
+          turns,
+          turnsById,
+          responseItemTurnId(projectedPayload) || activeTurnId || `turn-line-${sourceLineNumber}`,
+          sessionThreadId,
+          entry.timestamp
+        );
+        applyHistoryTimeZone(turn, sessionTimeZone);
+        const item = normalizeResponseItemForHistory(projectedPayload, sourceLineNumber, {
+          cwd: sessionCwd,
+          toolCallsByCallId,
+        });
+        if (item) {
+          if (shouldSkipDuplicateProposedPlanMessage(turn, item)) {
+            continue;
+          }
+          const itemTimestamp = historyItemTimestamp(item, entry.timestamp);
+          if (itemTimestamp && !item.createdAt) {
+            item.createdAt = itemTimestamp;
+          }
+          if (itemTimestamp && !item.timestamp) {
+            item.timestamp = itemTimestamp;
+          }
+          applyHistoryTimeZone(item, sessionTimeZone);
+          applyHistoryAssistantSourceAlias(item, turn.id, assistantAliasOccurrencesByBaseKey);
+          addHistoryItemToTurn(turn, item);
         }
-        applyHistoryTimeZone(item, sessionTimeZone);
-        applyHistoryAssistantSourceAlias(item, turn.id, assistantAliasOccurrencesByBaseKey);
-        addHistoryItemToTurn(turn, item);
       }
     }
   }
@@ -1310,6 +1343,13 @@ function shouldSkipResponseItemForHistory(payload, skippedCallIds) {
     return true;
   }
 
+  if (type === "tool_call" && isOrchestrationWaitCall(payload)) {
+    if (callId) {
+      skippedCallIds.add(callId);
+    }
+    return true;
+  }
+
   if (type === "tool_call" && isSubagentOrchestrationCall(payload)) {
     if (callId) {
       skippedCallIds.add(callId);

package/src/thread-list-provenance.js

@@ -0,0 +1,105 @@
+// FILE: thread-list-provenance.js
+// Purpose: Restores fork/automation provenance that app-server drops from thread list rows.
+// Layer: CLI helper
+// Exports: createThreadListProvenanceEnricher
+// Depends on: fs, ./session-jsonl-history, ./thread-row-enrichment
+
+const fs = require("fs");
+const { readSessionJsonlMetadataFromFile } = require("./session-jsonl-history");
+const { forEachThreadRowInResponse } = require("./thread-row-enrichment");
+
+// An entry is two short strings, so the cache stays far cheaper than re-reading
+// rollout heads. Sized well above any single thread/list page: a full unpaginated
+// list must not evict rows it is still walking, or every refresh re-reads the disk.
+const DEFAULT_MAX_ENTRIES = 4096;
+
+// app-server returns `forkedFromId: null` / `threadSource: null` on thread rows even
+// when the rollout's session_meta carries both. A thread forked by a desktop automation
+// copies the origin's name and preview, so without this the phone shows two identical
+// sidebar rows with no way to tell which is which. The rollout row already carries the
+// file path, and session_meta is written once at session start, so a bounded cache keyed
+// by thread id keeps this to one small head read per thread ever seen.
+function createThreadListProvenanceEnricher({
+  fsModule = fs,
+  maxEntries = DEFAULT_MAX_ENTRIES,
+} = {}) {
+  const cache = new Map();
+
+  function readProvenance(threadId, filePath) {
+    if (cache.has(threadId)) {
+      const cached = cache.get(threadId);
+      // Refresh insertion order so the Map behaves as an LRU.
+      cache.delete(threadId);
+      cache.set(threadId, cached);
+      return cached;
+    }
+
+    let provenance = { forkedFromId: "", threadSource: "" };
+    let readSessionMeta = false;
+    try {
+      const metadata = readSessionJsonlMetadataFromFile(filePath, { fsModule });
+      // The thread id only appears once session_meta is on disk; without it the read
+      // hit a rotated, unreadable, or still-being-written rollout.
+      readSessionMeta = Boolean(normalizeString(metadata?.threadId));
+      provenance = {
+        forkedFromId: normalizeString(metadata?.forkedFromId),
+        threadSource: normalizeString(metadata?.threadSource),
+      };
+    } catch {
+      // A rotated, half-written, or unreadable rollout simply leaves the row as-is.
+    }
+
+    // Only a real session_meta is worth remembering: it never changes again. Caching a
+    // failed read instead would strand a freshly forked thread without its badge until
+    // the bridge restarts, so those are retried on the next list.
+    if (!readSessionMeta) {
+      return provenance;
+    }
+
+    cache.set(threadId, provenance);
+    while (cache.size > Math.max(1, maxEntries)) {
+      cache.delete(cache.keys().next().value);
+    }
+    return provenance;
+  }
+
+  function attachToThread(thread) {
+    const threadId = normalizeString(thread?.id) || normalizeString(thread?.threadId);
+    const filePath = normalizeString(thread?.path) || normalizeString(thread?.rolloutPath);
+    if (!thread || typeof thread !== "object" || !threadId || !filePath) {
+      return thread;
+    }
+    // Never overwrite what app-server did resolve; this only fills the gaps.
+    if (normalizeString(thread.forkedFromId) && normalizeString(thread.threadSource)) {
+      return thread;
+    }
+
+    const provenance = readProvenance(threadId, filePath);
+    if (!normalizeString(thread.forkedFromId) && provenance.forkedFromId) {
+      thread.forkedFromId = provenance.forkedFromId;
+    }
+    if (!normalizeString(thread.threadSource) && provenance.threadSource) {
+      thread.threadSource = provenance.threadSource;
+    }
+    return thread;
+  }
+
+  function enrichResponse(method, envelope) {
+    return forEachThreadRowInResponse(method, envelope, attachToThread);
+  }
+
+  return {
+    attachToThread,
+    enrichResponse,
+    // Exposed for focused tests so cache growth stays provable.
+    cacheSize: () => cache.size,
+  };
+}
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+module.exports = {
+  createThreadListProvenanceEnricher,
+};

package/src/thread-row-enrichment.js

@@ -0,0 +1,43 @@
+// FILE: thread-row-enrichment.js
+// Purpose: One walk over the thread rows carried by thread/list, thread/read, and
+//          thread/resume responses, so every enricher shares the same shape handling
+//          and a response is traversed once no matter how many enrichers run on it.
+// Layer: CLI helper
+// Exports: forEachThreadRowInResponse
+// Depends on: (none)
+
+const THREAD_LIST_ROW_KEYS = ["data", "items", "threads"];
+
+function forEachThreadRowInResponse(method, envelope, visit) {
+  if (typeof visit !== "function") {
+    return envelope;
+  }
+  if (!envelope || typeof envelope !== "object" || envelope.error) {
+    return envelope;
+  }
+  const result = envelope.result;
+  if (!result || typeof result !== "object") {
+    return envelope;
+  }
+
+  if (method === "thread/read" || method === "thread/resume") {
+    if (result.thread && typeof result.thread === "object") {
+      visit(result.thread);
+    }
+    return envelope;
+  }
+
+  if (method === "thread/list") {
+    const key = THREAD_LIST_ROW_KEYS.find((candidate) => Array.isArray(result[candidate]));
+    for (const thread of key ? result[key] : []) {
+      if (thread && typeof thread === "object") {
+        visit(thread);
+      }
+    }
+  }
+  return envelope;
+}
+
+module.exports = {
+  forEachThreadRowInResponse,
+};