codesesh 0.6.0 → 0.7.0

package/dist/index.js

@@ -3,6 +3,7 @@ import {
   BookmarkStorageUnavailableError,
   classifySessionTags,
   computeIdentity,
+  createProjectScopeMatcher,
   createRegisteredAgents,
   deleteBookmark,
   extractSessionFileActivity,
@@ -11,21 +12,24 @@ import {
   getCursorDataPath,
   getSmartTagSourceTimestamp,
   importBookmarks,
+  isAgentCacheInitialized,
   listBookmarks,
   listCachedProjectGroups,
   listFileActivity,
+  listSessionFileActivity,
+  loadCachedSessionData,
+  loadCachedSessions,
+  matchesProjectScope,
   parseSearchQuery,
   perf,
   realFs,
   refreshPricingCache,
   resolveProviderRoots,
-  saveCachedSessions,
   scanSessions,
   searchFileActivitySessions,
   searchSessions,
-  syncSessionSearchIndex,
   upsertBookmark
-} from "./chunk-SQYHWMQV.js";
+} from "./chunk-JTHZVP6G.js";
 
 // src/index.ts
 import { defineCommand, runMain } from "citty";
@@ -191,6 +195,7 @@ function logSearchIndexSync(context, result, data = {}) {
 }
 
 // src/api/handlers.ts
+var DASHBOARD_RECENT_LIMIT = 10;
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -290,12 +295,6 @@ function filterSessionsByActivityWindow(sessions, from, to) {
     return true;
   });
 }
-function matchesProjectScope(session, cwd) {
-  if (!session.directory) return false;
-  const identity = computeIdentity(cwd, realFs);
-  if (session.project_identity?.key === identity.key) return true;
-  return session.directory.toLowerCase().includes(cwd.toLowerCase());
-}
 function sanitizeClientLogData(value) {
   if (!isRecord(value)) return {};
   return Object.fromEntries(
@@ -406,22 +405,9 @@ function attachProjectMetrics(projects, sessions) {
     };
   });
 }
-function matchesDashboardScope(session, scope) {
-  if (scope.agent && getSessionAgentName(session) !== scope.agent) return false;
-  if (scope.projectKey) {
-    const identity = session.project_identity;
-    if (!identity || identity.key !== scope.projectKey) return false;
-    if (scope.projectKind && identity.kind !== scope.projectKind) return false;
-  }
-  return true;
-}
-function filterSessionsByDashboardScope(sessions, scope) {
-  if (!scope.agent && !scope.projectKey) return sessions;
-  return sessions.filter((session) => matchesDashboardScope(session, scope));
-}
-function matchesRecentSearchFilters(session, options) {
+function matchesRecentSearchFilters(session, options, projectScope) {
   if (options.projectKey && session.project_identity?.key !== options.projectKey) return false;
-  if (options.cwd && !matchesProjectScope(session, options.cwd)) return false;
+  if (projectScope && !matchesProjectScope(session, projectScope)) return false;
   if (options.project) {
     const projectNeedle = options.project.toLowerCase();
     const projectText = [
@@ -438,9 +424,10 @@ function matchesRecentSearchFilters(session, options) {
   return true;
 }
 function recentSearchSessions(scanResult, options) {
+  const projectScope = options.cwd ? createProjectScopeMatcher(options.cwd) : null;
   const entries = options.agent ? [[options.agent, scanResult.byAgent[options.agent] ?? []]] : Object.entries(scanResult.byAgent);
   return entries.flatMap(
-    ([agentName, sessions]) => filterSessionsByActivityWindow(sessions, options.from, options.to).filter((session) => matchesRecentSearchFilters(session, options)).map((session) => ({ agentName, session }))
+    ([agentName, sessions]) => filterSessionsByActivityWindow(sessions, options.from, options.to).filter((session) => matchesRecentSearchFilters(session, options, projectScope)).map((session) => ({ agentName, session }))
   ).toSorted(
     (a, b) => (b.session.time_updated ?? b.session.time_created) - (a.session.time_updated ?? a.session.time_created)
   ).slice(0, options.limit).map(({ agentName, session }) => ({
@@ -459,6 +446,9 @@ function handleGetConfig(c, defaults) {
     }
   });
 }
+function handleGetScanStatus(c, scanSource) {
+  return c.json(scanSource.getScanStatus());
+}
 function handleGetAgents(c, scanSource, defaults = {}) {
   const scanResult = scanSource.getSnapshot();
   const { from, to } = defaults;
@@ -497,7 +487,8 @@ function handleGetSessions(c, scanSource, defaults = {}) {
   if (projectKey) {
     sessions = sessions.filter((s) => s.project_identity?.key === projectKey);
   } else if (cwd) {
-    sessions = sessions.filter((s) => matchesProjectScope(s, cwd));
+    const projectScope = createProjectScopeMatcher(cwd);
+    sessions = sessions.filter((s) => matchesProjectScope(s, projectScope));
   }
   sessions = filterSessionsByActivityWindow(sessions, from, to);
   if (tag) {
@@ -577,14 +568,26 @@ async function handleGetSessionData(c, scanSource) {
     return c.json({ error: `Unknown agent: ${agentName}` }, 404);
   }
   try {
+    const head = scanResult.byAgent[agentName]?.find((item) => item.id === sessionId);
     const loadStartedAt = performance.now();
-    const data = agent.getSessionData(sessionId);
+    const cachedData = loadCachedSessionData(agentName, sessionId);
+    const cachedMessageCount = cachedData?.stats.message_count ?? 0;
+    const cacheHasExpectedMessages = cachedData !== null && (cachedData.messages.length > 0 || cachedMessageCount === 0);
+    const data = cacheHasExpectedMessages ? cachedData : head ? agent.getSessionData(sessionId) : null;
     const loadDuration = performance.now() - loadStartedAt;
+    if (!data) {
+      appLogger.warn("api.session_data.cache_miss", {
+        agent: agentName,
+        session_id: sessionId,
+        duration_ms: Math.round(performance.now() - startedAt)
+      });
+      return c.json({ error: "Session cache not ready" }, 404);
+    }
     const tagStartedAt = performance.now();
-    const smartTags = classifySessionTags(data);
+    const smartTags = data.smart_tags ?? classifySessionTags(data);
     const tagDuration = performance.now() - tagStartedAt;
-    const head = scanResult.byAgent[agentName]?.find((item) => item.id === sessionId);
     const projectIdentity = data.project_identity ?? head?.project_identity ?? computeIdentity(data.directory, realFs);
+    const fileActivity = data.file_activity ?? (cacheHasExpectedMessages && cachedData ? listSessionFileActivity(agentName, sessionId) : extractSessionFileActivity(agentName, sessionId, projectIdentity.key, data.messages));
     appLogger.info("api.session_data", {
       agent: agentName,
       session_id: sessionId,
@@ -598,12 +601,7 @@ async function handleGetSessionData(c, scanSource) {
       project_identity: projectIdentity,
       smart_tags: smartTags,
       smart_tags_source_updated_at: getSmartTagSourceTimestamp(data),
-      file_activity: extractSessionFileActivity(
-        agentName,
-        sessionId,
-        projectIdentity.key,
-        data.messages
-      )
+      file_activity: fileActivity
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : "Failed to load session";
@@ -699,13 +697,17 @@ function startOfLocalDay(ts) {
 function resolveDashboardWindow(defaults, queryDays, queryFrom, queryTo) {
   const now = Date.now();
   const toTs = parseDateParam(queryTo, defaults.to) ?? now;
-  const parsedDays = queryDays ? parseInt(queryDays, 10) : NaN;
+  const hasQueryDays = queryDays != null && queryDays.trim() !== "";
+  const parsedDays = hasQueryDays ? parseInt(queryDays, 10) : NaN;
   let days = Number.isFinite(parsedDays) && parsedDays > 0 ? parsedDays : defaults.days;
   const fromFromQuery = parseDateParam(queryFrom, void 0);
   let fromTs;
   if (fromFromQuery != null) {
     fromTs = fromFromQuery;
     days ??= Math.max(1, Math.ceil((toTs - fromTs) / 864e5));
+  } else if (parsedDays === 0 || !hasQueryDays && defaults.days === 0) {
+    days = 0;
+    return { to: toTs, days };
   } else if (defaults.from != null) {
     fromTs = defaults.from;
     days ??= Math.max(1, Math.ceil((toTs - fromTs) / 864e5));
@@ -730,79 +732,81 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
     projectKind: optionalQueryValue(c.req.query("projectKind")),
     projectKey: optionalQueryValue(c.req.query("projectKey"))
   };
-  const scopedSessions = filterSessionsByDashboardScope(scanResult.sessions, scope);
-  const windowed = filterSessionsByActivityWindow(scopedSessions, from, to);
-  const scopedByAgent = Object.fromEntries(
-    Object.entries(scanResult.byAgent).filter(([name]) => !scope.agent || name.toLowerCase() === scope.agent).map(([name, sessions]) => [name, filterSessionsByDashboardScope(sessions, scope)])
-  );
-  const agentInfo = getAgentInfoMap(
-    Object.fromEntries(
-      Object.entries(scopedByAgent).map(([name, sessions]) => [
-        name,
-        filterSessionsByActivityWindow(sessions, from, to).length
-      ])
-    )
-  );
+  const agentMetrics = /* @__PURE__ */ new Map();
+  const agentMetricKeyByName = /* @__PURE__ */ new Map();
+  for (const name of Object.keys(scanResult.byAgent)) {
+    if (scope.agent && name.toLowerCase() !== scope.agent) continue;
+    agentMetrics.set(name, { sessions: 0, messages: 0, tokens: 0 });
+    agentMetricKeyByName.set(name.toLowerCase(), name);
+  }
+  const agentInfo = getAgentInfoMap({});
   const agentInfoMap = new Map(agentInfo.map((a) => [a.name, a]));
+  let totalSessions = 0;
   let totalMessages = 0;
   let totalTokens = 0;
   let totalCost = 0;
   let hasEstimatedCost = false;
   let latestActivity = 0;
-  for (const session of windowed) {
-    totalMessages += session.stats.message_count;
-    totalTokens += getTotalTokens(session.stats);
-    totalCost += session.stats.total_cost ?? 0;
-    if (session.stats.cost_source === "estimated") hasEstimatedCost = true;
-    const activity = getSessionActivityTime(session);
-    if (activity > latestActivity) latestActivity = activity;
-  }
-  const perAgent = Object.entries(scopedByAgent).map(([name, sessions]) => {
-    const info = agentInfoMap.get(name);
-    const agentWindowed = filterSessionsByActivityWindow(sessions, from, to);
-    let messages = 0;
-    let tokens = 0;
-    for (const s of agentWindowed) {
-      messages += s.stats.message_count;
-      tokens += getTotalTokens(s.stats);
-    }
-    return {
-      name,
-      displayName: info?.displayName ?? name,
-      icon: info?.icon ?? "",
-      sessions: agentWindowed.length,
-      messages,
-      tokens
-    };
-  }).filter((item) => item.sessions > 0).sort((a, b) => b.sessions - a.sessions);
+  const recentCandidates = [];
+  const modelAgg = /* @__PURE__ */ new Map();
   const dailyMap = /* @__PURE__ */ new Map();
   const dailyTokenMap = /* @__PURE__ */ new Map();
-  const bucketStart = startOfLocalDay(from);
-  const bucketDays = Math.floor((startOfLocalDay(to) - bucketStart) / 864e5) + 1;
-  for (let i = 0; i < bucketDays; i += 1) {
-    const ts = bucketStart + i * 864e5;
-    const key = toLocalDateKey(ts);
-    dailyMap.set(key, { date: key, sessions: 0, messages: 0 });
-    dailyTokenMap.set(key, { date: key, input: 0, output: 0, cache_read: 0, cache_create: 0 });
+  if (from != null) {
+    const bucketStart = startOfLocalDay(from);
+    const bucketDays = Math.floor((startOfLocalDay(to) - bucketStart) / 864e5) + 1;
+    for (let i = 0; i < bucketDays; i += 1) {
+      const ts = bucketStart + i * 864e5;
+      const key = toLocalDateKey(ts);
+      dailyMap.set(key, { date: key, sessions: 0, messages: 0 });
+      dailyTokenMap.set(key, { date: key, input: 0, output: 0, cache_read: 0, cache_create: 0 });
+    }
   }
-  const modelAgg = /* @__PURE__ */ new Map();
-  for (const session of windowed) {
-    const key = toLocalDateKey(getSessionActivityTime(session));
-    const bucket = dailyMap.get(key);
-    if (bucket) {
-      bucket.sessions += 1;
-      bucket.messages += session.stats.message_count;
-    }
-    const tokenBucket = dailyTokenMap.get(key);
-    if (tokenBucket) {
-      const cacheRead = session.stats.total_cache_read_tokens ?? 0;
-      const cacheCreate = session.stats.total_cache_create_tokens ?? 0;
-      const pureInput = session.stats.total_input_tokens - cacheRead - cacheCreate;
-      tokenBucket.input += Math.max(0, pureInput);
-      tokenBucket.output += session.stats.total_output_tokens;
-      tokenBucket.cache_read += cacheRead;
-      tokenBucket.cache_create += cacheCreate;
+  for (const session of scanResult.sessions) {
+    const agentName = getSessionAgentName(session);
+    if (scope.agent && agentName !== scope.agent) continue;
+    if (scope.projectKey) {
+      const identity = session.project_identity;
+      if (!identity || identity.key !== scope.projectKey) continue;
+      if (scope.projectKind && identity.kind !== scope.projectKind) continue;
     }
+    const activity = getSessionActivityTime(session);
+    if (from != null && activity < from) continue;
+    if (activity > to) continue;
+    const messageCount = session.stats.message_count;
+    const sessionTokens = getTotalTokens(session.stats);
+    totalSessions += 1;
+    totalMessages += messageCount;
+    totalTokens += sessionTokens;
+    totalCost += session.stats.total_cost ?? 0;
+    if (session.stats.cost_source === "estimated") hasEstimatedCost = true;
+    if (activity > latestActivity) latestActivity = activity;
+    const metricKey = agentMetricKeyByName.get(agentName);
+    if (metricKey) {
+      const metric = agentMetrics.get(metricKey);
+      metric.sessions += 1;
+      metric.messages += messageCount;
+      metric.tokens += sessionTokens;
+    }
+    const key = toLocalDateKey(activity);
+    let bucket = dailyMap.get(key);
+    if (!bucket) {
+      bucket = { date: key, sessions: 0, messages: 0 };
+      dailyMap.set(key, bucket);
+    }
+    bucket.sessions += 1;
+    bucket.messages += messageCount;
+    let tokenBucket = dailyTokenMap.get(key);
+    if (!tokenBucket) {
+      tokenBucket = { date: key, input: 0, output: 0, cache_read: 0, cache_create: 0 };
+      dailyTokenMap.set(key, tokenBucket);
+    }
+    const cacheRead = session.stats.total_cache_read_tokens ?? 0;
+    const cacheCreate = session.stats.total_cache_create_tokens ?? 0;
+    const pureInput = session.stats.total_input_tokens - cacheRead - cacheCreate;
+    tokenBucket.input += Math.max(0, pureInput);
+    tokenBucket.output += session.stats.total_output_tokens;
+    tokenBucket.cache_read += cacheRead;
+    tokenBucket.cache_create += cacheCreate;
     if (session.model_usage) {
       for (const [model, tokens] of Object.entries(session.model_usage)) {
         const entry = modelAgg.get(model);
@@ -814,17 +818,41 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
         }
       }
     }
+    let recentIndex = recentCandidates.length;
+    for (let i = 0; i < recentCandidates.length; i += 1) {
+      if (activity > recentCandidates[i].activity) {
+        recentIndex = i;
+        break;
+      }
+    }
+    if (recentIndex < DASHBOARD_RECENT_LIMIT) {
+      recentCandidates.splice(recentIndex, 0, { session, activity });
+      if (recentCandidates.length > DASHBOARD_RECENT_LIMIT) recentCandidates.pop();
+    }
   }
-  const dailyActivity = [...dailyMap.values()];
-  const dailyTokenActivity = [...dailyTokenMap.values()];
+  const perAgent = [...agentMetrics.entries()].map(([name, metrics]) => {
+    const info = agentInfoMap.get(name);
+    return {
+      name,
+      displayName: info?.displayName ?? name,
+      icon: info?.icon ?? "",
+      sessions: metrics.sessions,
+      messages: metrics.messages,
+      tokens: metrics.tokens
+    };
+  }).filter((item) => item.sessions > 0).sort((a, b) => b.sessions - a.sessions);
+  const dailyActivity = [...dailyMap.values()].sort((a, b) => a.date.localeCompare(b.date));
+  const dailyTokenActivity = [...dailyTokenMap.values()].sort(
+    (a, b) => a.date.localeCompare(b.date)
+  );
   const modelDistribution = [...modelAgg.entries()].map(([model, { tokens, sessions: count }]) => ({ model, tokens, sessions: count })).sort((a, b) => b.tokens - a.tokens);
-  const recentSessions = [...windowed].sort((a, b) => getSessionActivityTime(b) - getSessionActivityTime(a)).slice(0, 10).map((session) => {
+  const recentSessions = recentCandidates.map(({ session }) => {
     const agentKey = getSessionAgentName(session);
     return { ...session, agentName: agentKey };
   });
   const data = {
     totals: {
-      sessions: windowed.length,
+      sessions: totalSessions,
       messages: totalMessages,
       tokens: totalTokens,
       cost: totalCost,
@@ -862,7 +890,11 @@ function createSseResponse(store, signal) {
 `));
         };
         write("connected", { timestamp: Date.now() });
-        const unsubscribe = store.subscribe((event) => {
+        write("scan-status", store.getScanStatus());
+        const unsubscribeSessions = store.subscribe((event) => {
+          write(event.type, event);
+        });
+        const unsubscribeScanStatus = store.subscribeScanStatus((event) => {
           write(event.type, event);
         });
         const heartbeat = setInterval(() => {
@@ -870,7 +902,8 @@ function createSseResponse(store, signal) {
         }, 15e3);
         const close = () => {
           clearInterval(heartbeat);
-          unsubscribe();
+          unsubscribeSessions();
+          unsubscribeScanStatus();
           controller.close();
         };
         signal.addEventListener("abort", close, { once: true });
@@ -896,6 +929,9 @@ function createApiRoutes(scanSource, store, options = {}) {
     days: options.defaultSessionDays
   };
   api.get("/config", (c) => handleGetConfig(c, listDefaults));
+  if (store) {
+    api.get("/status", (c) => handleGetScanStatus(c, store));
+  }
   api.get("/agents", (c) => handleGetAgents(c, scanSource, listDefaults));
   api.get("/projects", (c) => handleGetProjects(c, scanSource, listDefaults));
   api.get("/sessions", (c) => handleGetSessions(c, scanSource, listDefaults));
@@ -947,6 +983,13 @@ function getServerStartupErrorMessage(error, port) {
   }
   return error instanceof Error ? error.message : `\u542F\u52A8\u670D\u52A1\u5668\u5931\u8D25: ${String(error)}`;
 }
+function isAddressInUse(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EADDRINUSE";
+}
+function getListeningPort(server, fallback) {
+  const address = server.address();
+  return typeof address === "object" && address !== null ? address.port : fallback;
+}
 async function createServer(port, store, options = {}) {
   const app = new Hono2();
   app.use("*", async (c, next) => {
@@ -987,26 +1030,48 @@ async function createServer(port, store, options = {}) {
     app.use("/*", serveStatic({ root: webDistPath }));
     app.get("/*", serveStatic({ root: webDistPath, path: "index.html" }));
   }
-  const server = serve({ fetch: app.fetch, port });
-  try {
-    await waitForListening(server);
-  } catch (error) {
-    appLogger.error("server.listen.error", { port, error });
-    server.close();
-    if (store.shutdown) {
-      await store.shutdown();
+  const attempts = Math.max(1, options.portFallbackAttempts ?? 1);
+  let server = null;
+  let actualPort = port;
+  for (let offset = 0; offset < attempts; offset += 1) {
+    const candidatePort = port + offset;
+    server = serve({ fetch: app.fetch, port: candidatePort });
+    try {
+      await waitForListening(server);
+      actualPort = getListeningPort(server, candidatePort);
+      break;
+    } catch (error) {
+      appLogger.error("server.listen.error", { port: candidatePort, error });
+      server.close();
+      if (isAddressInUse(error) && offset < attempts - 1) {
+        continue;
+      }
+      if (store.shutdown) {
+        await store.shutdown();
+      }
+      if (isAddressInUse(error) && attempts > 1) {
+        throw new Error(
+          `\u7AEF\u53E3 ${port}-${port + attempts - 1} \u5747\u5DF2\u88AB\u5360\u7528\uFF0C\u8BF7\u5173\u95ED\u73B0\u6709\u8FDB\u7A0B\u6216\u6539\u7528 --port \u6307\u5B9A\u5176\u4ED6\u7AEF\u53E3\u3002`
+        );
+      }
+      throw new Error(getServerStartupErrorMessage(error, candidatePort));
     }
-    throw new Error(getServerStartupErrorMessage(error, port));
   }
-  const url = `http://localhost:${port}`;
-  appLogger.info("server.listen", { port, url });
+  const url = `http://localhost:${actualPort}`;
+  appLogger.info("server.listen", { port: actualPort, requested_port: port, url });
   return {
     url,
-    shutdown: () => {
-      appLogger.info("server.shutdown", { port });
-      server.close();
+    shutdown: async () => {
+      appLogger.info("server.shutdown", { port: actualPort });
+      await new Promise((resolve4) => {
+        if (!server) {
+          resolve4();
+          return;
+        }
+        server.close(() => resolve4());
+      });
       if (store.shutdown) {
-        void store.shutdown();
+        await store.shutdown();
       }
     }
   };
@@ -1042,49 +1107,89 @@ function sessionSignature(session) {
     session.stats.total_tokens ?? 0
   ]);
 }
-function buildAgentCacheMeta(agent) {
+function buildAgentCacheMeta(agent, sessionIds) {
   const metaMap = agent.getSessionMetaMap?.();
   const meta = {};
   if (!metaMap) return meta;
   for (const [id, data] of metaMap.entries()) {
+    if (sessionIds && !sessionIds.has(id)) continue;
     meta[id] = { id, ...data };
   }
   return meta;
 }
-function buildUpdateEvent(agentName, previousSessions, nextSessions) {
+function attachMissingProjectIdentities(sessions) {
+  const identities = /* @__PURE__ */ new Map();
+  return sessions.map((session) => {
+    if (session.project_identity) return session;
+    const directory = session.directory || "";
+    let identity = identities.get(directory);
+    if (!identity) {
+      identity = computeIdentity(directory, realFs);
+      identities.set(directory, identity);
+    }
+    return { ...session, project_identity: identity };
+  });
+}
+function buildRefreshDiff(agentName, previousSessions, nextSessions, candidateChangedIds = []) {
   const previousMap = new Map(previousSessions.map((session) => [session.id, session]));
   const nextMap = new Map(nextSessions.map((session) => [session.id, session]));
+  const candidateChangedIdSet = new Set(candidateChangedIds);
+  const changedSessions = [];
+  const removedSessionIds = [];
   let newSessions = 0;
   let updatedSessions = 0;
   let removedSessions = 0;
-  for (const [id, session] of nextMap.entries()) {
+  nextSessions.forEach((session, index) => {
+    const id = session.id;
     const previous = previousMap.get(id);
     if (!previous) {
       newSessions += 1;
-      continue;
+      changedSessions.push({ session, sortIndex: index });
+      return;
     }
-    if (sessionSignature(previous) !== sessionSignature(session)) {
+    const hasSignatureChange = sessionSignature(previous) !== sessionSignature(session);
+    const hasContentChange = candidateChangedIdSet.has(id);
+    if (hasSignatureChange || hasContentChange) {
       updatedSessions += 1;
     }
-  }
+    if (hasContentChange || hasSignatureChange) {
+      changedSessions.push({ session, sortIndex: index });
+    }
+  });
   for (const id of previousMap.keys()) {
     if (!nextMap.has(id)) {
       removedSessions += 1;
+      removedSessionIds.push(id);
     }
   }
   if (newSessions === 0 && updatedSessions === 0 && removedSessions === 0) {
-    return null;
+    return { event: null, changedSessions, removedSessionIds };
   }
   return {
-    type: "sessions-updated",
-    changedAgents: [agentName],
-    newSessions,
-    updatedSessions,
-    removedSessions,
-    totalSessions: nextSessions.length,
-    timestamp: Date.now()
+    changedSessions,
+    removedSessionIds,
+    event: {
+      type: "sessions-updated",
+      changedAgents: [agentName],
+      newSessions,
+      updatedSessions,
+      removedSessions,
+      totalSessions: nextSessions.length,
+      timestamp: Date.now(),
+      changedSessionHeads: changedSessions.map(({ session }) => ({ agentName, session })),
+      removedSessionRefs: removedSessionIds.map((sessionId) => ({ agentName, sessionId }))
+    }
   };
 }
+function restoreAgentCacheMeta(agent, meta) {
+  agent.setSessionMetaMap?.(new Map(Object.entries(meta)));
+}
+function sourceFingerprintFromMeta(meta) {
+  return typeof meta?.sourceFingerprint === "string" ? meta.sourceFingerprint : null;
+}
+function sourcePathFromMeta(meta) {
+  return typeof meta?.sourcePath === "string" ? meta.sourcePath : null;
+}
 function toAbsolutePath(path) {
   return isAbsolute(path) ? path : resolve2(path);
 }
@@ -1127,6 +1232,23 @@ function isRelatedPath(changedPath, targetPath) {
   return isSameOrChildPath(targetPath, changedPath) || isSameOrChildPath(changedPath, targetPath);
 }
 function mergeEvents(previous, next) {
+  const changedSessionHeads = /* @__PURE__ */ new Map();
+  const removedSessionRefs = /* @__PURE__ */ new Map();
+  const sessionKey = (agentName, sessionId) => `${agentName}\0${sessionId}`;
+  const addChanged = (item) => {
+    const key = sessionKey(item.agentName, item.session.id);
+    removedSessionRefs.delete(key);
+    changedSessionHeads.set(key, item);
+  };
+  const addRemoved = (item) => {
+    const key = sessionKey(item.agentName, item.sessionId);
+    changedSessionHeads.delete(key);
+    removedSessionRefs.set(key, item);
+  };
+  for (const item of previous.changedSessionHeads) addChanged(item);
+  for (const item of previous.removedSessionRefs) addRemoved(item);
+  for (const item of next.changedSessionHeads) addChanged(item);
+  for (const item of next.removedSessionRefs) addRemoved(item);
   return {
     type: "sessions-updated",
     changedAgents: Array.from(/* @__PURE__ */ new Set([...previous.changedAgents, ...next.changedAgents])),
@@ -1134,7 +1256,9 @@ function mergeEvents(previous, next) {
     updatedSessions: previous.updatedSessions + next.updatedSessions,
     removedSessions: previous.removedSessions + next.removedSessions,
     totalSessions: next.totalSessions,
-    timestamp: next.timestamp
+    timestamp: next.timestamp,
+    changedSessionHeads: [...changedSessionHeads.values()],
+    removedSessionRefs: [...removedSessionRefs.values()]
   };
 }
 function mergeScopes(target, scopes) {
@@ -1163,7 +1287,10 @@ function resolveAgentWatchTargets(agentName) {
         { path: "data/claudecode" }
       ];
     case "codex":
-      return [{ root: roots.codexRoot, path: join2(roots.codexRoot, "sessions") }];
+      return [
+        { path: join2(roots.codexRoot, "sessions") },
+        { path: join2(roots.codexRoot, "session_index.jsonl") }
+      ];
     case "cursor":
       return cursorDataPath ? [
         {
@@ -1187,18 +1314,31 @@ function resolveAgentWatchTargets(agentName) {
   }
 }
 var LiveScanStore = class {
-  constructor(watchEnabled = true, scanOptions = {}, startupScanOptions = {}) {
+  constructor(watchEnabled = true, scanOptions = {}, startupScanOptions = {}, storeOptions = {}) {
     this.watchEnabled = watchEnabled;
     this.scanOptions = scanOptions;
     this.startupScanOptions = startupScanOptions;
+    this.storeOptions = storeOptions;
   }
   watchEnabled;
   scanOptions;
   startupScanOptions;
+  storeOptions;
   agents = [];
   byAgent = {};
   sessions = [];
   listeners = /* @__PURE__ */ new Set();
+  scanStatusListeners = /* @__PURE__ */ new Set();
+  scanStatus = {
+    active: false,
+    phase: "idle",
+    pendingAgents: [],
+    scanningAgents: [],
+    completedAgents: [],
+    agentStatuses: {},
+    totalAgents: 0,
+    updatedAt: Date.now()
+  };
   refreshTimers = /* @__PURE__ */ new Map();
   refreshTimestamps = /* @__PURE__ */ new Map();
   refreshInFlight = /* @__PURE__ */ new Set();
@@ -1209,41 +1349,82 @@ var LiveScanStore = class {
   stablePaths = /* @__PURE__ */ new Map();
   pendingEvent = null;
   pendingEventTimer = null;
-  initialSearchIndexTimer = null;
+  backgroundRefreshTimer = null;
   searchIndexWorker = null;
+  pendingSearchIndexJobs = [];
+  shuttingDown = false;
   async initialize() {
     const startedAt = performance.now();
+    const deferInitialRefresh = this.storeOptions.deferInitialRefresh === true;
     appLogger.info("scan.initial.start", {
       watch_enabled: this.watchEnabled,
       agents: this.scanOptions.agents,
       use_cache: this.scanOptions.useCache ?? true,
       startup_from: this.startupScanOptions.from,
-      startup_to: this.startupScanOptions.to
+      startup_to: this.startupScanOptions.to,
+      deferred: deferInitialRefresh || void 0
     });
     const initialResult = await scanSessions({
       ...this.scanOptions,
-      ...this.startupScanOptions,
+      ...deferInitialRefresh ? this.startupScanOptions : {},
       useCache: this.scanOptions.useCache ?? true,
       smartRefresh: false,
-      writeCache: this.startupScanOptions.from != null || this.startupScanOptions.to != null ? false : void 0,
-      includeSmartTags: this.startupScanOptions.from != null || this.startupScanOptions.to != null ? false : void 0
+      cacheOnly: deferInitialRefresh,
+      writeCache: deferInitialRefresh ? false : this.scanOptions.writeCache,
+      smartTagWorkerUrl: this.getSmartTagWorkerUrl() ?? void 0,
+      includeSmartTags: deferInitialRefresh ? false : void 0
     });
     this.applyScanResult(initialResult);
+    const indexStartedAt = performance.now();
+    if (!deferInitialRefresh) {
+      await this.enqueueSearchIndexJobs(
+        "scan.initial",
+        this.buildFullSearchIndexJobs("scan.initial")
+      );
+    }
+    const indexDuration = performance.now() - indexStartedAt;
     appLogger.info("scan.initial.done", {
       duration_ms: Math.round(performance.now() - startedAt),
+      index_ms: deferInitialRefresh ? void 0 : Math.round(indexDuration),
+      deferred: deferInitialRefresh || void 0,
       sessions: this.sessions.length,
       agents: Object.fromEntries(
         Object.entries(this.byAgent).map(([key, value]) => [key, value.length])
-      )
+      ),
+      agent_timings: initialResult.timings ? Object.fromEntries(
+        Object.entries(initialResult.timings).map(([name, t]) => [
+          name,
+          {
+            total_ms: Math.round(t.total),
+            cache_load_ms: t.cacheLoad != null ? Math.round(t.cacheLoad) : void 0,
+            check_changes_ms: t.checkChanges != null ? Math.round(t.checkChanges) : void 0,
+            scan_ms: t.scan != null ? Math.round(t.scan) : void 0,
+            identity_ms: t.identity != null ? Math.round(t.identity) : void 0,
+            tags_ms: t.tags != null ? Math.round(t.tags) : void 0
+          }
+        ])
+      ) : void 0
     });
     if (this.watchEnabled) {
       this.startWatching();
-      this.initialSearchIndexTimer = setTimeout(() => {
-        this.initialSearchIndexTimer = null;
-        this.startSearchIndexWorker("scan.initial.background");
-      }, 1e3);
     }
   }
+  startBackgroundRefresh() {
+    if (this.backgroundRefreshTimer) {
+      return;
+    }
+    const agentNames = this.agents.map((agent) => agent.name);
+    this.startScanBatch(agentNames, "scanning");
+    this.backgroundRefreshTimer = setTimeout(() => {
+      this.backgroundRefreshTimer = null;
+      for (const agentName of agentNames) {
+        this.scheduleRefresh(agentName, 0);
+      }
+      if (agentNames.length === 0) {
+        this.finishScanBatch();
+      }
+    }, 0);
+  }
   getSnapshot() {
     return {
       sessions: this.sessions,
@@ -1251,13 +1432,35 @@ var LiveScanStore = class {
       agents: this.agents
     };
   }
+  getScanStatus() {
+    return {
+      type: "scan-status",
+      ...this.scanStatus,
+      pendingAgents: [...this.scanStatus.pendingAgents],
+      scanningAgents: [...this.scanStatus.scanningAgents],
+      completedAgents: [...this.scanStatus.completedAgents],
+      agentStatuses: Object.fromEntries(
+        Object.entries(this.scanStatus.agentStatuses).map(([agentName, status]) => [
+          agentName,
+          { ...status }
+        ])
+      )
+    };
+  }
   subscribe(listener) {
     this.listeners.add(listener);
     return () => {
       this.listeners.delete(listener);
     };
   }
+  subscribeScanStatus(listener) {
+    this.scanStatusListeners.add(listener);
+    return () => {
+      this.scanStatusListeners.delete(listener);
+    };
+  }
   async shutdown() {
+    this.shuttingDown = true;
     for (const timer of this.refreshTimers.values()) {
       clearTimeout(timer);
     }
@@ -1273,14 +1476,18 @@ var LiveScanStore = class {
       clearTimeout(this.pendingEventTimer);
       this.pendingEventTimer = null;
     }
-    if (this.initialSearchIndexTimer) {
-      clearTimeout(this.initialSearchIndexTimer);
-      this.initialSearchIndexTimer = null;
+    if (this.backgroundRefreshTimer) {
+      clearTimeout(this.backgroundRefreshTimer);
+      this.backgroundRefreshTimer = null;
     }
     if (this.searchIndexWorker) {
       await this.searchIndexWorker.terminate();
       this.searchIndexWorker = null;
     }
+    for (const batch of this.pendingSearchIndexJobs) {
+      batch.reject(new Error("Live scan store shut down"));
+    }
+    this.pendingSearchIndexJobs = [];
     this.pendingEvent = null;
     await Promise.all(this.watchers.map((watcher) => watcher.close()));
     this.watchers = [];
@@ -1298,6 +1505,157 @@ var LiveScanStore = class {
       listener(event);
     }
   }
+  emitScanStatus() {
+    const event = this.getScanStatus();
+    for (const listener of this.scanStatusListeners) {
+      listener(event);
+    }
+  }
+  updateScanStatus(next) {
+    this.scanStatus = next;
+    this.emitScanStatus();
+  }
+  startScanBatch(agentNames, phase) {
+    const uniqueAgentNames = [...new Set(agentNames)];
+    const now = Date.now();
+    const agentStatuses = Object.fromEntries(
+      uniqueAgentNames.map((agentName) => [
+        agentName,
+        {
+          agentName,
+          status: "pending",
+          processed: 0,
+          sessions: this.byAgent[agentName]?.length ?? 0,
+          updatedAt: now
+        }
+      ])
+    );
+    this.updateScanStatus({
+      active: uniqueAgentNames.length > 0,
+      phase: uniqueAgentNames.length > 0 ? phase : "idle",
+      pendingAgents: uniqueAgentNames,
+      scanningAgents: [],
+      completedAgents: [],
+      agentStatuses,
+      totalAgents: uniqueAgentNames.length,
+      startedAt: uniqueAgentNames.length > 0 ? now : void 0,
+      updatedAt: now,
+      completedAt: uniqueAgentNames.length > 0 ? void 0 : now
+    });
+  }
+  setScanPhase(phase) {
+    if (!this.scanStatus.active) return;
+    this.updateScanStatus({
+      ...this.scanStatus,
+      phase,
+      updatedAt: Date.now()
+    });
+  }
+  beginAgentScan(agentName) {
+    if (!this.scanStatus.active) {
+      this.startScanBatch([agentName], "scanning");
+    }
+    const pendingAgents = this.scanStatus.pendingAgents.filter((agent) => agent !== agentName);
+    const scanningAgents = [.../* @__PURE__ */ new Set([...this.scanStatus.scanningAgents, agentName])];
+    const completedAgents = this.scanStatus.completedAgents.filter((agent) => agent !== agentName);
+    const existingStatus = this.scanStatus.agentStatuses[agentName];
+    const agentStatuses = {
+      ...this.scanStatus.agentStatuses,
+      [agentName]: {
+        agentName,
+        status: "scanning",
+        total: existingStatus?.total,
+        processed: existingStatus?.processed ?? 0,
+        sessions: existingStatus?.sessions ?? this.byAgent[agentName]?.length ?? 0,
+        startedAt: existingStatus?.startedAt ?? Date.now(),
+        updatedAt: Date.now()
+      }
+    };
+    this.updateScanStatus({
+      ...this.scanStatus,
+      active: true,
+      phase: this.scanStatus.phase === "initializing" ? "initializing" : "scanning",
+      pendingAgents,
+      scanningAgents,
+      completedAgents,
+      agentStatuses,
+      totalAgents: Math.max(
+        this.scanStatus.totalAgents,
+        pendingAgents.length + scanningAgents.length
+      ),
+      updatedAt: Date.now(),
+      completedAt: void 0
+    });
+  }
+  updateAgentScanProgress(agentName, progress) {
+    const status = this.scanStatus.agentStatuses[agentName];
+    if (!status || status.status !== "scanning") return;
+    this.updateScanStatus({
+      ...this.scanStatus,
+      agentStatuses: {
+        ...this.scanStatus.agentStatuses,
+        [agentName]: {
+          ...status,
+          total: progress.total ?? status.total,
+          processed: progress.processed ?? status.processed,
+          sessions: progress.sessions ?? status.sessions,
+          updatedAt: Date.now()
+        }
+      },
+      updatedAt: Date.now()
+    });
+  }
+  finishAgentScan(agentName) {
+    const pendingAgents = this.scanStatus.pendingAgents.filter((agent) => agent !== agentName);
+    const scanningAgents = this.scanStatus.scanningAgents.filter((agent) => agent !== agentName);
+    const completedAgents = [.../* @__PURE__ */ new Set([...this.scanStatus.completedAgents, agentName])];
+    const active = pendingAgents.length > 0 || scanningAgents.length > 0;
+    const now = Date.now();
+    const previousStatus = this.scanStatus.agentStatuses[agentName];
+    const sessions = this.byAgent[agentName]?.length ?? previousStatus?.sessions ?? 0;
+    const total = previousStatus?.total ?? previousStatus?.processed;
+    this.updateScanStatus({
+      ...this.scanStatus,
+      active,
+      phase: active ? "scanning" : "idle",
+      pendingAgents,
+      scanningAgents,
+      completedAgents,
+      agentStatuses: {
+        ...this.scanStatus.agentStatuses,
+        [agentName]: {
+          agentName,
+          status: "complete",
+          total,
+          processed: total,
+          sessions,
+          startedAt: previousStatus?.startedAt,
+          updatedAt: now,
+          completedAt: now
+        }
+      },
+      updatedAt: now,
+      completedAt: active ? void 0 : now
+    });
+  }
+  finishScanBatch() {
+    const now = Date.now();
+    this.updateScanStatus({
+      ...this.scanStatus,
+      active: false,
+      phase: "idle",
+      pendingAgents: [],
+      scanningAgents: [],
+      agentStatuses: Object.fromEntries(
+        Object.entries(this.scanStatus.agentStatuses).map(([agentName, status]) => [
+          agentName,
+          { ...status, status: "complete", completedAt: status.completedAt ?? now, updatedAt: now }
+        ])
+      ),
+      updatedAt: now,
+      completedAt: now
+    });
+  }
   queueEvent(event) {
     this.pendingEvent = this.pendingEvent ? mergeEvents(this.pendingEvent, event) : event;
     if (this.pendingEventTimer) {
@@ -1315,9 +1673,6 @@ var LiveScanStore = class {
   rebuildSessions() {
     this.sessions = sortSessions(Object.values(this.byAgent).flat());
   }
-  hasStartupWindow() {
-    return this.startupScanOptions.from != null || this.startupScanOptions.to != null;
-  }
   getSearchIndexWorkerUrl() {
     const workerUrl = new URL("./search-index-worker.js", import.meta.url);
     if (workerUrl.protocol === "file:" && !existsSync3(fileURLToPath2(workerUrl))) {
@@ -1325,21 +1680,114 @@ var LiveScanStore = class {
     }
     return workerUrl;
   }
-  startSearchIndexWorker(context) {
-    if (this.searchIndexWorker) return;
+  getSmartTagWorkerUrl() {
+    const workerUrl = new URL("./smart-tag-worker.js", import.meta.url);
+    if (workerUrl.protocol === "file:" && !existsSync3(fileURLToPath2(workerUrl))) {
+      return null;
+    }
+    return workerUrl;
+  }
+  getScanRefreshWorkerUrl() {
+    const workerUrl = new URL("./scan-refresh-worker.js", import.meta.url);
+    if (workerUrl.protocol === "file:" && !existsSync3(fileURLToPath2(workerUrl))) {
+      return null;
+    }
+    return workerUrl;
+  }
+  scanAgentInWorker(agent, previousSessions, changedIds, scanOptions) {
+    const workerUrl = this.getScanRefreshWorkerUrl();
+    if (!workerUrl) return null;
+    return new Promise((resolve4, reject) => {
+      const worker = new Worker(workerUrl, {
+        workerData: {
+          agentName: agent.name,
+          previousSessions,
+          changedIds,
+          scanOptions,
+          meta: buildAgentCacheMeta(agent)
+        }
+      });
+      worker.unref();
+      let settled = false;
+      const finish = (callback) => {
+        if (settled) return;
+        settled = true;
+        void worker.terminate();
+        callback();
+      };
+      worker.on("message", (message) => {
+        if (message.type === "progress") {
+          this.updateAgentScanProgress(agent.name, message.progress);
+          return;
+        }
+        if (message.type === "done") {
+          finish(() => resolve4({ sessions: message.sessions, meta: message.meta }));
+          return;
+        }
+        finish(() => reject(new Error(message.error)));
+      });
+      worker.once("error", (error) => {
+        finish(() => reject(error));
+      });
+      worker.once("exit", (code) => {
+        if (!settled && code !== 0) {
+          finish(() => reject(new Error(`Scan refresh worker exited with code ${code}`)));
+        }
+      });
+    });
+  }
+  buildFullSearchIndexJobs(context) {
+    return this.agents.map((agent) => {
+      const cached = loadCachedSessions(agent.name, { ignoreTtl: true });
+      if (cached) {
+        return {
+          kind: "full",
+          context,
+          agentName: agent.name,
+          sessions: cached.sessions,
+          meta: cached.meta
+        };
+      }
+      return {
+        kind: "full",
+        context,
+        agentName: agent.name,
+        sessions: this.byAgent[agent.name] ?? [],
+        meta: buildAgentCacheMeta(agent)
+      };
+    });
+  }
+  enqueueSearchIndexJobs(context, jobs) {
+    if (jobs.length === 0) return Promise.resolve();
+    return new Promise((resolve4, reject) => {
+      const batch = { context, jobs, resolve: resolve4, reject };
+      if (this.searchIndexWorker) {
+        this.pendingSearchIndexJobs.push(batch);
+        appLogger.debug("search_index.worker_queued", {
+          context,
+          jobs: jobs.length,
+          pending_jobs: this.pendingSearchIndexJobs.length
+        });
+        return;
+      }
+      this.startSearchIndexJobBatch(batch);
+    });
+  }
+  startSearchIndexJobBatch(batch) {
     const workerUrl = this.getSearchIndexWorkerUrl();
     if (!workerUrl) {
-      appLogger.warn("search_index.worker_missing", { context });
+      appLogger.warn("search_index.worker_missing", { context: batch.context });
+      batch.resolve();
       return;
     }
+    let settled = false;
     const worker = new Worker(workerUrl, {
       workerData: {
-        context,
-        agentNames: this.agents.map((agent) => agent.name),
-        sessionsByAgent: this.byAgent,
-        metaByAgent: Object.fromEntries(
-          this.agents.map((agent) => [agent.name, buildAgentCacheMeta(agent)])
-        )
+        context: batch.context,
+        jobs: batch.jobs,
+        agentNames: [],
+        sessionsByAgent: {},
+        metaByAgent: {}
       }
     });
     worker.unref();
@@ -1352,15 +1800,29 @@ var LiveScanStore = class {
           duration_ms: Math.round(message.durationMs),
           sessions: message.sessions
         });
+        settled = true;
+        batch.resolve();
       }
     });
     worker.on("error", (error) => {
-      appLogger.error("search_index.worker_error", { context, error });
+      appLogger.error("search_index.worker_error", { context: batch.context, error });
+      if (!settled) {
+        settled = true;
+        batch.reject(error);
+      }
     });
     worker.on("exit", (code) => {
       this.searchIndexWorker = null;
       if (code !== 0) {
-        appLogger.warn("search_index.worker_exit", { context, code });
+        appLogger.warn("search_index.worker_exit", { context: batch.context, code });
+        if (!settled) {
+          settled = true;
+          batch.reject(new Error(`Search index worker exited with code ${code}`));
+        }
+      }
+      if (this.pendingSearchIndexJobs.length > 0) {
+        const pendingBatch = this.pendingSearchIndexJobs.shift();
+        this.startSearchIndexJobBatch(pendingBatch);
       }
     });
   }
@@ -1385,7 +1847,7 @@ var LiveScanStore = class {
     this.byAgent = {};
     for (const agent of this.agents) {
       this.byAgent[agent.name] = sortSessions(result.byAgent[agent.name] ?? []);
-      this.refreshTimestamps.set(agent.name, Date.now());
+      this.refreshTimestamps.set(agent.name, result.cacheTimestamps?.[agent.name] ?? Date.now());
     }
     this.rebuildSessions();
   }
@@ -1398,6 +1860,59 @@ var LiveScanStore = class {
   applyFilters(sessions) {
     return filterSessions(sessions, { ...this.scanOptions, ...this.startupScanOptions });
   }
+  canSyncSources(agent) {
+    return Boolean(agent.listSessionSources && agent.scanSessionSource);
+  }
+  syncAgentSources(agent, cachedSessions, cachedMeta) {
+    const sessionMap = new Map(cachedSessions.map((session) => [session.id, session]));
+    const sourceRefs = agent.listSessionSources();
+    const currentIds = new Set(sourceRefs.map((source) => source.sessionId));
+    const changedIds = /* @__PURE__ */ new Set();
+    for (const source of sourceRefs) {
+      const cachedSession = sessionMap.get(source.sessionId);
+      const cached = cachedMeta[source.sessionId];
+      const sameSource = sourcePathFromMeta(cached) === source.sourcePath;
+      const sameFingerprint = sourceFingerprintFromMeta(cached) === source.fingerprint;
+      if (cachedSession && sameSource && sameFingerprint) continue;
+      const next = agent.scanSessionSource(source.sourcePath);
+      changedIds.add(source.sessionId);
+      if (next) {
+        sessionMap.set(next.id, next);
+      } else {
+        sessionMap.delete(source.sessionId);
+      }
+    }
+    for (const session of cachedSessions) {
+      if (!currentIds.has(session.id)) {
+        sessionMap.delete(session.id);
+        changedIds.add(session.id);
+      }
+    }
+    const sessions = attachMissingProjectIdentities([...sessionMap.values()]);
+    const persistenceDiff = buildRefreshDiff(agent.name, cachedSessions, sessions, [...changedIds]);
+    return {
+      sessions,
+      changedIds: [...changedIds],
+      persistenceDiff
+    };
+  }
+  async refreshInitialIndex() {
+    const startedAt = performance.now();
+    const context = "scan.initial.background";
+    try {
+      await this.enqueueSearchIndexJobs(context, this.buildFullSearchIndexJobs(context));
+      appLogger.info(`${context}.complete`, {
+        duration_ms: Math.round(performance.now() - startedAt),
+        sessions: this.sessions.length
+      });
+    } catch (error) {
+      if (this.shuttingDown) {
+        return;
+      }
+      appLogger.error(`${context}.error`, { error });
+      console.error("[search] Background index sync failed:", error);
+    }
+  }
   startWatching() {
     const scopesByRoot = /* @__PURE__ */ new Map();
     for (const agent of this.agents) {
@@ -1606,6 +2121,7 @@ var LiveScanStore = class {
       return;
     }
     this.refreshInFlight.add(agentName);
+    this.beginAgentScan(agentName);
     try {
       await this.runRefresh(agentName);
     } catch (error) {
@@ -1613,6 +2129,7 @@ var LiveScanStore = class {
       console.error(`[${agentName}] Session refresh failed:`, error);
     } finally {
       this.refreshInFlight.delete(agentName);
+      this.finishAgentScan(agentName);
       if (this.pendingRefreshes.delete(agentName)) {
         this.scheduleRefresh(agentName, PENDING_REFRESH_DELAY_MS);
       }
@@ -1628,14 +2145,72 @@ var LiveScanStore = class {
       return;
     }
     const previousSessions = this.byAgent[agentName] ?? [];
+    const cached = loadCachedSessions(agentName, { ignoreTtl: true });
+    const refreshBaseline = cached?.sessions ?? previousSessions;
+    const cacheTimestamp = cached?.timestamp ?? this.refreshTimestamps.get(agentName) ?? 0;
+    if (cached) {
+      restoreAgentCacheMeta(agent, cached.meta);
+    }
+    const isInitialized = isAgentCacheInitialized(agentName);
     let nextSessions = previousSessions;
-    if (!agent.isAvailable()) {
+    let fullScanSessions = null;
+    let preciseChangedIds = null;
+    let usedIncrementalScan = false;
+    let persistenceDiff = null;
+    let availabilityDuration = 0;
+    let checkDuration = 0;
+    let scanDuration = 0;
+    let filterDuration = 0;
+    let diffDuration = 0;
+    let persistDuration = 0;
+    let searchIndexDuration = 0;
+    let persistentJobKind;
+    const availabilityStartedAt = performance.now();
+    const isAvailable = agent.isAvailable();
+    availabilityDuration = performance.now() - availabilityStartedAt;
+    if (!isAvailable) {
       nextSessions = [];
       this.refreshTimestamps.set(agentName, Date.now());
-    } else if (previousSessions.length > 0 && agent.checkForChanges && agent.incrementalScan) {
+    } else if (!isInitialized) {
+      this.setScanPhase("initializing");
+      const scanStartedAt = performance.now();
+      const workerResult = this.scanAgentInWorker(agent, previousSessions, null, {});
+      if (workerResult) {
+        const result = await workerResult;
+        nextSessions = result.sessions;
+        agent.setSessionMetaMap?.(new Map(Object.entries(result.meta)));
+      } else {
+        nextSessions = await Promise.resolve(
+          agent.scan({
+            onProgress: (progress) => this.updateAgentScanProgress(agentName, progress)
+          })
+        );
+      }
+      fullScanSessions = attachMissingProjectIdentities(nextSessions);
+      nextSessions = fullScanSessions;
+      scanDuration = performance.now() - scanStartedAt;
+      this.refreshTimestamps.set(agentName, Date.now());
+    } else if (cached && this.canSyncSources(agent)) {
+      const scanStartedAt = performance.now();
+      const result = this.syncAgentSources(agent, cached.sessions, cached.meta);
+      nextSessions = result.sessions;
+      preciseChangedIds = result.changedIds;
+      usedIncrementalScan = true;
+      persistenceDiff = result.persistenceDiff;
+      scanDuration = performance.now() - scanStartedAt;
+      this.refreshTimestamps.set(agentName, Date.now());
+      if (result.changedIds.length === 0) {
+        appLogger.debug("scan.refresh.unchanged", {
+          agent: agentName,
+          duration_ms: Math.round(performance.now() - startedAt)
+        });
+      }
+    } else if (refreshBaseline.length > 0 && agent.checkForChanges && agent.incrementalScan) {
+      const checkStartedAt = performance.now();
       const checkResult = await Promise.resolve(
-        agent.checkForChanges(this.refreshTimestamps.get(agentName) ?? 0, previousSessions)
+        agent.checkForChanges(cacheTimestamp, refreshBaseline)
       );
+      checkDuration = performance.now() - checkStartedAt;
       this.refreshTimestamps.set(agentName, checkResult.timestamp);
       if (!checkResult.hasChanges) {
         appLogger.debug("scan.refresh.unchanged", {
@@ -1644,30 +2219,93 @@ var LiveScanStore = class {
         });
         return;
       }
+      preciseChangedIds = checkResult.changedIds ?? null;
+      usedIncrementalScan = Array.isArray(checkResult.changedIds);
+      const scanStartedAt = performance.now();
       nextSessions = await Promise.resolve(
-        agent.incrementalScan(previousSessions, checkResult.changedIds ?? [])
+        agent.incrementalScan(refreshBaseline, checkResult.changedIds ?? [])
+      );
+      const nextBaseline = attachMissingProjectIdentities(nextSessions);
+      persistenceDiff = buildRefreshDiff(
+        agentName,
+        refreshBaseline,
+        nextBaseline,
+        preciseChangedIds ?? []
       );
+      nextSessions = nextBaseline;
+      scanDuration = performance.now() - scanStartedAt;
     } else {
-      nextSessions = await Promise.resolve(agent.scan(this.startupScanOptions));
+      const scanStartedAt = performance.now();
+      const workerResult = this.scanAgentInWorker(agent, previousSessions, null, {});
+      if (workerResult) {
+        const result = await workerResult;
+        nextSessions = result.sessions;
+        agent.setSessionMetaMap?.(new Map(Object.entries(result.meta)));
+      } else {
+        nextSessions = await Promise.resolve(
+          agent.scan({
+            onProgress: (progress) => this.updateAgentScanProgress(agentName, progress)
+          })
+        );
+      }
+      fullScanSessions = attachMissingProjectIdentities(nextSessions);
+      nextSessions = fullScanSessions;
+      scanDuration = performance.now() - scanStartedAt;
       this.refreshTimestamps.set(agentName, Date.now());
     }
+    nextSessions = attachMissingProjectIdentities(nextSessions);
+    const filterStartedAt = performance.now();
     nextSessions = this.applyFilters(nextSessions);
-    if (!this.hasStartupWindow()) {
-      saveCachedSessions(agentName, nextSessions, buildAgentCacheMeta(agent));
-    }
-    const searchIndexOptions = pendingPathCount >= SEARCH_INDEX_BULK_PENDING_PATH_THRESHOLD ? { isBulk: true } : void 0;
-    const syncResult = searchIndexOptions ? syncSessionSearchIndex(
-      agentName,
-      nextSessions,
-      (sessionId) => agent.getSessionData(sessionId),
-      searchIndexOptions
-    ) : syncSessionSearchIndex(
+    filterDuration = performance.now() - filterStartedAt;
+    const diffStartedAt = performance.now();
+    const diff = buildRefreshDiff(
       agentName,
+      previousSessions,
       nextSessions,
-      (sessionId) => agent.getSessionData(sessionId)
+      preciseChangedIds ?? []
     );
-    logSearchIndexSync("scan.refresh", syncResult, { pending_paths: pendingPathCount });
-    const event = buildUpdateEvent(agentName, previousSessions, nextSessions);
+    diffDuration = performance.now() - diffStartedAt;
+    const searchIndexOptions = pendingPathCount >= SEARCH_INDEX_BULK_PENDING_PATH_THRESHOLD ? { isBulk: true } : void 0;
+    const canPersistIncrementally = usedIncrementalScan;
+    const persistentChanges = persistenceDiff?.changedSessions ?? diff.changedSessions;
+    const persistentRemovedSessionIds = persistenceDiff?.removedSessionIds ?? diff.removedSessionIds;
+    const changedSessionIds = canPersistIncrementally ? new Set(persistentChanges.map(({ session }) => session.id)) : void 0;
+    const cacheMeta = buildAgentCacheMeta(agent, changedSessionIds);
+    const persistStartedAt = performance.now();
+    const persistentJob = canPersistIncrementally ? {
+      kind: "changes",
+      context: "scan.refresh",
+      agentName,
+      changes: persistentChanges,
+      removedSessionIds: persistentRemovedSessionIds,
+      meta: cacheMeta,
+      ...searchIndexOptions ? { searchIndexOptions } : {}
+    } : fullScanSessions ? {
+      kind: "full",
+      context: "scan.refresh",
+      agentName,
+      sessions: fullScanSessions,
+      meta: buildAgentCacheMeta(agent),
+      saveCache: true,
+      ...searchIndexOptions ? { searchIndexOptions } : {}
+    } : null;
+    if (persistentJob) {
+      persistentJobKind = persistentJob.kind;
+      const persist = this.enqueueSearchIndexJobs("scan.refresh", [persistentJob]);
+      if (!isInitialized && persistentJob.kind === "full") {
+        await persist;
+      } else {
+        void persist.catch((error) => {
+          appLogger.error("scan.refresh.persist.error", { agent: agentName, error });
+          console.error(`[${agentName}] Session persistence failed:`, error);
+        });
+      }
+    }
+    persistDuration = performance.now() - persistStartedAt;
+    const searchIndexStartedAt = performance.now();
+    searchIndexDuration = performance.now() - searchIndexStartedAt;
+    logSearchIndexSync("scan.refresh", null, { pending_paths: pendingPathCount });
+    const event = diff.event;
     this.byAgent[agentName] = sortSessions(nextSessions);
     this.rebuildSessions();
     if (event) {
@@ -1682,8 +2320,15 @@ var LiveScanStore = class {
       updated_sessions: event?.updatedSessions ?? 0,
       removed_sessions: event?.removedSessions ?? 0,
       pending_paths: pendingPathCount,
-      search_index_mode: syncResult?.mode,
-      search_index_rebuild_duration_ms: syncResult?.rebuildDurationMs == null ? void 0 : Math.round(syncResult.rebuildDurationMs)
+      availability_ms: Math.round(availabilityDuration),
+      check_ms: Math.round(checkDuration),
+      scan_ms: Math.round(scanDuration),
+      filter_ms: Math.round(filterDuration),
+      diff_ms: Math.round(diffDuration),
+      persist_ms: Math.round(persistDuration),
+      search_index_ms: Math.round(searchIndexDuration),
+      persistent_index_worker_job: persistentJobKind,
+      persistent_index_skipped: !persistentJob || void 0
     });
   }
 };
@@ -1700,42 +2345,36 @@ var pkg = JSON.parse(readFileSync(resolve3(__dirname, "../package.json"), "utf-8
 var VERSION = pkg.version;
 
 // src/output.ts
-function printScanResults(agents, result) {
+function printScanResults(agents) {
   consola.log("");
   consola.box({
     title: "CodeSesh",
-    message: `v${VERSION} \u2022 ${result.sessions.length} sessions discovered`,
+    message: `v${VERSION} \u2022 local session browser`,
     style: {
       padding: 1,
       borderColor: "cyan"
     }
   });
   consola.log("");
-  const rows = [];
-  let availableCount = 0;
-  for (const agent of agents) {
-    const sessions = result.byAgent[agent.name];
-    const count = sessions?.length ?? 0;
-    if (count > 0) {
-      availableCount++;
-      rows.push(`  ${green("\u2714")} ${pad(agent.displayName)} ${dim(`${count} sessions`)}`);
-    } else {
-      rows.push(`  ${dim("\u2716")} ${pad(agent.displayName)} ${dim("not found")}`);
-    }
-  }
-  consola.log(rows.join("\n"));
-  consola.log("");
-  consola.info(`Active: ${availableCount}/${agents.length} agents`);
+  consola.info(
+    `Indexing ${agents.map((agent) => agent.displayName).join(", ")} sessions in the background.`
+  );
+  consola.info("The Web UI will update automatically as sessions are discovered.");
   consola.log("");
 }
-function pad(text, length = 16) {
-  return text.padEnd(length);
-}
-function green(text) {
-  return `\x1B[32m${text}\x1B[0m`;
-}
-function dim(text) {
-  return `\x1B[2m${text}\x1B[0m`;
+
+// src/ports.ts
+var DEFAULT_PORT = 4521;
+var DEFAULT_PORT_FALLBACK_ATTEMPTS = 20;
+function parsePort(value) {
+  const port = parseInt(value ?? "", 10);
+  return Number.isNaN(port) ? DEFAULT_PORT : port;
+}
+function hasExplicitPortArg(argv) {
+  return argv.some((arg, index) => {
+    if (arg === "--port" || arg === "-p") return index < argv.length - 1;
+    return arg.startsWith("--port=") || /^-p\d+$/.test(arg);
+  });
 }
 
 // src/index.ts
@@ -1762,7 +2401,7 @@ var main = defineCommand({
       type: "string",
       alias: "p",
       description: "HTTP server port",
-      default: "4321"
+      default: String(DEFAULT_PORT)
     },
     agent: {
       type: "string",
@@ -1821,7 +2460,8 @@ var main = defineCommand({
   },
   async run({ args }) {
     const startedAt = performance.now();
-    const port = parseInt(args.port, 10) || 4321;
+    const port = parsePort(args.port);
+    const explicitPort = hasExplicitPortArg(process.argv.slice(2));
     const noOpen = args.noOpen;
     const jsonOnly = args.json;
     const trace = args.trace;
@@ -1840,7 +2480,7 @@ var main = defineCommand({
       log_path: appLogger.getLogPath()
     });
     if (clearCache) {
-      const { clearCache: clear } = await import("./dist-NT4CH6KD.js");
+      const { clearCache: clear } = await import("./dist-FQAQSHHO.js");
       clear();
       appLogger.info("cache.clear");
       console.log("Cache cleared.");
@@ -1867,6 +2507,8 @@ var main = defineCommand({
       if (!Number.isNaN(days) && days > 0) {
         listDefaultFrom = Date.now() - days * 24 * 60 * 60 * 1e3;
         listDefaultDays = days;
+      } else if (days === 0) {
+        listDefaultDays = 0;
       }
     }
     const listDefaultTo = args.to ? parseDateToTimestamp(args.to) : void 0;
@@ -1876,7 +2518,9 @@ var main = defineCommand({
       useCache
     };
     const startupScanOptions = targetSession || jsonOnly ? {} : { from: listDefaultFrom, to: listDefaultTo };
-    const store = new LiveScanStore(!jsonOnly, scanOptions, startupScanOptions);
+    const store = new LiveScanStore(!jsonOnly, scanOptions, startupScanOptions, {
+      deferInitialRefresh: !jsonOnly
+    });
     await store.initialize();
     const result = store.getSnapshot();
     appLogger.info("cli.scan_ready", {
@@ -1918,18 +2562,37 @@ var main = defineCommand({
       return;
     }
     const agents = createRegisteredAgents();
-    printScanResults(agents, result);
-    let url;
+    printScanResults(agents);
+    let app;
     try {
-      ({ url } = await createServer(port, store, {
+      app = await createServer(port, store, {
         defaultSessionFrom: listDefaultFrom,
         defaultSessionTo: listDefaultTo,
-        defaultSessionDays: listDefaultDays
-      }));
+        defaultSessionDays: listDefaultDays,
+        portFallbackAttempts: explicitPort ? 1 : DEFAULT_PORT_FALLBACK_ATTEMPTS
+      });
     } catch (error) {
       console.error(getServerStartupErrorMessage(error, port));
       process.exit(1);
     }
+    const { url } = app;
+    if (!jsonOnly) {
+      store.startBackgroundRefresh();
+    }
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      appLogger.info("cli.shutdown", { signal });
+      await app.shutdown();
+      process.exit(0);
+    };
+    process.once("SIGINT", (signal) => {
+      void shutdown(signal);
+    });
+    process.once("SIGTERM", (signal) => {
+      void shutdown(signal);
+    });
     console.log(`  ${url}`);
     console.log("");
     appLogger.info("cli.ready", {