codesesh 0.16.0 → 0.18.0

package/dist/index.js

@@ -2,29 +2,29 @@
 import {
   appLogger,
   logSearchIndexSync
-} from "./chunk-EWC6IODK.js";
+} from "./chunk-DHNP33L4.js";
 import {
   FileSystemSessionSource,
+  SessionAliasValidationError,
   StateStorageUnavailableError,
+  addCalendarDays,
   attachMissingProjectIdentities,
+  attachProjectMetrics,
   buildAgentCacheMeta,
   buildDashboard,
-  classifySessionTags,
-  computeIdentity,
   computeSessionDiff,
+  countCalendarDays,
   createProjectScopeMatcher,
   createRegisteredAgents,
   deleteBookmark,
   deleteSessionAlias,
   executeSessionSearch,
-  extractSessionFileActivity,
+  filterSessionSearchCandidates,
+  formatSessionReference,
   getAgentInfoMap,
   getAgentLastFullSyncAt,
-  getCursorDataPath,
   getSessionActivityTime,
-  getSessionAgentName,
-  getSmartTagSourceTimestamp,
-  getTotalTokens,
+  getSessionAgentKey,
   importBookmarks,
   isAgentCacheInitialized,
   isProjectIdentityKind,
@@ -32,25 +32,26 @@ import {
   listCachedProjectGroups,
   listFileActivity,
   listSessionAliases,
-  listSessionFileActivity,
-  loadCachedSessionDataEntry,
   loadCachedSessions,
   markAgentFullSyncCompleted,
   matchesProjectIdentity,
   matchesProjectScope,
-  matchesSessionSearchFilters,
+  materializeSessionDetailResponse,
   mergeSearchQueryOptions,
+  mergeSessionsUpdatedEvents,
+  mergeSortedSessions,
+  normalizeSessionReference,
   perf,
-  realFs,
+  publishPendingPricing,
   refreshPricingCache,
-  resolveProviderRoots,
   scanSessions,
+  sessionRoutePath,
   sessionSignature,
   sortSessions,
-  startOfLocalDay,
+  startOfCalendarDay,
   upsertBookmark,
   upsertSessionAlias
-} from "./chunk-MWSJTNOW.js";
+} from "./chunk-HIYT2ZJL.js";
 
 // src/index.ts
 import { defineCommand, runMain } from "citty";
@@ -62,6 +63,7 @@ import { compress } from "hono/compress";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { existsSync } from "fs";
+import { createServer as createHttpsServer } from "https";
 import { resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 
@@ -69,7 +71,7 @@ import { fileURLToPath } from "url";
 import { Hono } from "hono";
 
 // src/time-window-resolution.ts
-var DAY_MS = 24 * 60 * 60 * 1e3;
+var ROLLING_DAY_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_DASHBOARD_DAYS = 30;
 function resolveTimeWindow(request) {
   return request.mode === "cli" ? resolveCliWindow(request) : resolveDashboardWindow(request);
@@ -82,7 +84,7 @@ function resolveCliWindow(request) {
   const days = parseDays(request.days);
   if (days === 0) return { to, days };
   if (days == null || days < 0) return { to };
-  const rollingFrom = now - days * DAY_MS;
+  const rollingFrom = now - days * ROLLING_DAY_MS;
   return Number.isFinite(rollingFrom) ? { from: rollingFrom, to, days } : { to };
 }
 function resolveDashboardWindow(request) {
@@ -94,19 +96,19 @@ function resolveDashboardWindow(request) {
   let days = parsedDays != null && parsedDays > 0 ? parsedDays : defaults.days;
   const queryFrom = parseOptionalDate(request.query.from);
   if (queryFrom != null) {
-    days ??= elapsedDays(queryFrom, to);
+    days ??= countCalendarDays(queryFrom, to);
     return { from: queryFrom, to, days };
   }
   if (parsedDays === 0 || !hasQueryDays && defaults.days === 0) {
     return { to, days: 0 };
   }
   if (defaults.from != null) {
-    days ??= elapsedDays(defaults.from, to);
+    days ??= countCalendarDays(defaults.from, to);
     return { from: defaults.from, to, days };
   }
   const resolvedDays = days != null && days > 0 ? days : DEFAULT_DASHBOARD_DAYS;
   return {
-    from: startOfLocalDay(to) - (resolvedDays - 1) * DAY_MS,
+    from: addCalendarDays(startOfCalendarDay(to), -(resolvedDays - 1)),
     to,
     days: resolvedDays
   };
@@ -125,32 +127,101 @@ function parseOptionalDate(value) {
 function parseDays(value) {
   if (value == null) return void 0;
   const days = Number.parseInt(value, 10);
-  return Number.isSafeInteger(days) && Number.isSafeInteger(days * DAY_MS) ? days : void 0;
-}
-function elapsedDays(from, to) {
-  return Math.max(1, Math.ceil((to - from) / DAY_MS));
+  return Number.isSafeInteger(days) && Number.isSafeInteger(days * ROLLING_DAY_MS) ? days : void 0;
 }
 
-// src/api/handlers.ts
-function cacheMatchesCurrentSource(cachedMeta, currentMeta) {
-  const currentFingerprint = currentMeta?.sourceFingerprint;
-  if (typeof currentFingerprint !== "string") return true;
-  return cachedMeta?.sourceFingerprint === currentFingerprint;
+// src/api/query-params.ts
+var SMART_TAGS = [
+  "bugfix",
+  "refactoring",
+  "feature-dev",
+  "testing",
+  "docs",
+  "git-ops",
+  "build-deploy",
+  "exploration",
+  "planning"
+];
+var SEARCH_LIMIT_MAX = 100;
+var SEARCH_LIMIT_DEFAULT = 50;
+function searchParams(c) {
+  return new URL(c.req.url ?? "http://localhost/", "http://localhost/").searchParams;
+}
+function queryValues(params, ...names) {
+  return names.flatMap(
+    (name) => params.getAll(name).flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean)
+  );
+}
+function optionalQueryValue(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function parseDateParam(value, fallback) {
+  if (value == null) return fallback;
+  const ts = new Date(value).getTime();
+  return Number.isNaN(ts) ? fallback : ts;
+}
+function parseNumberParam(value) {
+  if (value == null || !value.trim()) return void 0;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : void 0;
+}
+function parseSmartTags(values) {
+  const tags = values.map((value) => value.toLowerCase()).filter((value) => SMART_TAGS.includes(value));
+  return tags.length > 0 ? [...new Set(tags)] : void 0;
+}
+function parseFileActivityKind(value) {
+  if (value === "read" || value === "edit" || value === "write" || value === "delete") {
+    return value;
+  }
+  return void 0;
+}
+function parseProjectIdentityFilter(kindValue, keyValue) {
+  const kind = optionalQueryValue(kindValue);
+  const key = optionalQueryValue(keyValue);
+  if (!kind && !key) return void 0;
+  if (!kind || !key || !isProjectIdentityKind(kind)) return null;
+  return { kind, key };
+}
+function parseSearchOptions(c, defaults, projectIdentity) {
+  const params = searchParams(c);
+  const limitValue = parseNumberParam(params.get("limit") ?? void 0);
+  return {
+    agent: optionalQueryValue(params.get("agent") ?? void 0),
+    project: optionalQueryValue(params.get("project") ?? void 0),
+    projectKind: projectIdentity?.kind,
+    projectKey: projectIdentity?.key,
+    cwd: optionalQueryValue(params.get("cwd") ?? void 0),
+    tags: parseSmartTags(queryValues(params, "tag", "tags", "signal")),
+    tools: queryValues(params, "tool", "tools").map((tool) => tool.toLowerCase()),
+    file: optionalQueryValue(params.get("file") ?? params.get("path") ?? void 0),
+    fileKind: parseFileActivityKind(
+      optionalQueryValue(params.get("fileKind") ?? params.get("fileActivity") ?? void 0)
+    ),
+    costMin: parseNumberParam(params.get("costMin") ?? void 0),
+    costMax: parseNumberParam(params.get("costMax") ?? void 0),
+    from: parseDateParam(params.get("from") ?? void 0, defaults.from),
+    to: parseDateParam(params.get("to") ?? void 0, defaults.to),
+    limit: limitValue && limitValue > 0 ? Math.min(limitValue, SEARCH_LIMIT_MAX) : SEARCH_LIMIT_DEFAULT
+  };
 }
-function getSessionAliasKey(agentKey, sessionId) {
-  return `${agentKey.toLowerCase()}\0${sessionId}`;
+function filterSessionsByActivityWindow(sessions, from, to) {
+  if (from == null && to == null) return sessions;
+  return sessions.filter((session) => {
+    const activity = getSessionActivityTime(session);
+    if (from != null && activity < from) return false;
+    if (to != null && activity > to) return false;
+    return true;
+  });
 }
-function getSessionAgentKey(session) {
-  return session.slug.split("/")[0]?.toLowerCase() ?? "";
+
+// src/api/session-aliases-view.ts
+function aliasKey(reference) {
+  return `${reference.agentName.toLowerCase()}\0${reference.sessionId}`;
 }
-function loadSessionAliasMap() {
+function loadAliasMap() {
   try {
-    return new Map(
-      listSessionAliases().map((alias) => [
-        getSessionAliasKey(alias.agentKey, alias.sessionId),
-        alias.alias
-      ])
-    );
+    return new Map(listSessionAliases().map((alias) => [aliasKey(alias.reference), alias]));
   } catch (error) {
     if (!(error instanceof StateStorageUnavailableError)) {
       appLogger.warn("api.session_aliases.load_failed", {
@@ -160,52 +231,97 @@ function loadSessionAliasMap() {
     return /* @__PURE__ */ new Map();
   }
 }
-function isStateStorageUnavailable(error) {
-  return error instanceof StateStorageUnavailableError;
+function buildAliasView() {
+  const aliases = loadAliasMap();
+  return {
+    size: aliases.size,
+    get: (reference) => aliases.get(aliasKey(reference))?.alias,
+    decorate(record, reference) {
+      const alias = aliases.get(aliasKey(reference))?.alias;
+      return alias ? { ...record, display_title: alias } : record;
+    },
+    entries: () => aliases.values()
+  };
 }
-function withDisplayTitle(session, agentKey, aliases) {
-  const alias = aliases.get(getSessionAliasKey(agentKey, session.id));
-  return alias ? { ...session, display_title: alias } : session;
+var cachedView = null;
+function loadAliasView() {
+  return cachedView ??= buildAliasView();
 }
-function withBookmarkDisplayTitle(bookmark, aliases) {
-  const alias = aliases.get(getSessionAliasKey(bookmark.agentKey, bookmark.sessionId));
-  return alias ? { ...bookmark, display_title: alias } : bookmark;
+function invalidateAliasView() {
+  cachedView = null;
 }
-function withFileActivityDisplayTitle(activity, aliases) {
+function decorateBookmark(bookmark, aliases) {
   return {
-    ...activity,
-    session: withDisplayTitle(activity.session, activity.agent_name, aliases)
+    ...bookmark,
+    session: aliases.decorate(bookmark.session, bookmark.reference)
   };
 }
-function findSessionByAliasKey(scanResult, aliasKey) {
-  const separatorIndex = aliasKey.indexOf("\0");
-  const agentName = aliasKey.slice(0, separatorIndex);
-  const sessionId = aliasKey.slice(separatorIndex + 1);
-  return scanResult.byAgent[agentName]?.find((session) => session.id === sessionId);
+function decorateFileActivity(activity, aliases) {
+  return {
+    ...activity,
+    session: aliases.decorate(activity.session, activity.reference)
+  };
 }
 function findAliasSearchResults(query, options, scanResult, aliases) {
   const search = mergeSearchQueryOptions(query, options);
   const needle = search.text.trim().toLowerCase();
   if (!needle || aliases.size === 0) return [];
-  const projectScope = search.options.cwd ? createProjectScopeMatcher(search.options.cwd) : null;
+  const sessionsByAgent = /* @__PURE__ */ new Map();
+  const lookupSession = (agentName, sessionId) => {
+    let byId = sessionsByAgent.get(agentName);
+    if (!byId) {
+      byId = new Map((scanResult.byAgent[agentName] ?? []).map((item) => [item.id, item]));
+      sessionsByAgent.set(agentName, byId);
+    }
+    return byId.get(sessionId);
+  };
   const results = [];
-  for (const [aliasKey, alias] of aliases) {
-    if (!alias.toLowerCase().includes(needle)) continue;
-    const session = findSessionByAliasKey(scanResult, aliasKey);
+  for (const alias of aliases.entries()) {
+    if (!alias.alias.toLowerCase().includes(needle)) continue;
+    const { agentName, sessionId } = alias.reference;
+    const session = lookupSession(agentName, sessionId);
     if (!session) continue;
-    const agentName = aliasKey.slice(0, aliasKey.indexOf("\0"));
-    if (!matchesSessionSearchFilters(agentName, session, search.options, projectScope)) continue;
     results.push({
-      agentName,
-      session: withDisplayTitle(session, agentName, aliases),
+      reference: alias.reference,
+      session: aliases.decorate(session, alias.reference),
       snippet: `Alias \xB7 ${session.directory}`,
       matchType: "title"
     });
   }
-  return results.sort(
+  return filterSessionSearchCandidates(results, search.options).sort(
     (a, b) => getSessionActivityTime(b.session) - getSessionActivityTime(a.session)
   );
 }
+
+// src/api/handlers.ts
+var SNAPSHOT_AGGREGATION_CACHE_LIMIT = 64;
+var snapshotAggregationCaches = /* @__PURE__ */ new WeakMap();
+function getSnapshotAggregation(source, sessions, key, build) {
+  let cache = snapshotAggregationCaches.get(source);
+  if (!cache || cache.sessions !== sessions) {
+    cache = { sessions, values: /* @__PURE__ */ new Map() };
+    snapshotAggregationCaches.set(source, cache);
+  }
+  const cacheKey = JSON.stringify(key);
+  if (cache.values.has(cacheKey)) return cache.values.get(cacheKey);
+  const value = build();
+  if (cache.values.size >= SNAPSHOT_AGGREGATION_CACHE_LIMIT) {
+    const oldestKey = cache.values.keys().next().value;
+    if (oldestKey != null) cache.values.delete(oldestKey);
+  }
+  cache.values.set(cacheKey, value);
+  return value;
+}
+function withStorageErrors(handler, onUnavailable) {
+  try {
+    return handler();
+  } catch (error) {
+    if (error instanceof StateStorageUnavailableError) {
+      return onUnavailable();
+    }
+    throw error;
+  }
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -213,15 +329,14 @@ function isSessionStats(value) {
   if (!isRecord(value)) return false;
   return typeof value.message_count === "number" && typeof value.total_input_tokens === "number" && typeof value.total_output_tokens === "number" && typeof value.total_cost === "number" && (value.total_tokens == null || typeof value.total_tokens === "number");
 }
-function parseBookmarkPayload(value) {
+function parseBookmarkSession(value, reference) {
   if (!isRecord(value)) return null;
-  if (typeof value.agentKey !== "string" || typeof value.sessionId !== "string" || typeof value.fullPath !== "string" || typeof value.title !== "string" || typeof value.directory !== "string" || typeof value.time_created !== "number" || value.time_updated != null && typeof value.time_updated !== "number" || !isSessionStats(value.stats)) {
+  if (value.id !== reference.sessionId || typeof value.slug !== "string" || typeof value.title !== "string" || typeof value.directory !== "string" || typeof value.time_created !== "number" || value.time_updated != null && typeof value.time_updated !== "number" || !isSessionStats(value.stats)) {
     return null;
   }
   return {
-    agentKey: value.agentKey,
-    sessionId: value.sessionId,
-    fullPath: value.fullPath,
+    id: reference.sessionId,
+    slug: formatSessionReference(reference),
     title: value.title,
     directory: value.directory,
     time_created: value.time_created,
@@ -229,70 +344,38 @@ function parseBookmarkPayload(value) {
     stats: value.stats
   };
 }
-function parseDateParam(value, fallback) {
-  if (value == null) return fallback;
-  const ts = new Date(value).getTime();
-  return Number.isNaN(ts) ? fallback : ts;
-}
-function parseNumberParam(value) {
-  if (value == null || !value.trim()) return void 0;
-  const number = Number(value);
-  return Number.isFinite(number) ? number : void 0;
-}
-function searchParams(c) {
-  return new URL(c.req.url ?? "http://localhost/", "http://localhost/").searchParams;
-}
-function queryValues(params, ...names) {
-  return names.flatMap(
-    (name) => params.getAll(name).flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean)
-  );
-}
-function parseSmartTags(values) {
-  const tags = values.map((value) => value.toLowerCase()).filter(
-    (value) => [
-      "bugfix",
-      "refactoring",
-      "feature-dev",
-      "testing",
-      "docs",
-      "git-ops",
-      "build-deploy",
-      "exploration",
-      "planning"
-    ].includes(value)
-  );
-  return tags.length > 0 ? [...new Set(tags)] : void 0;
-}
-function parseSearchOptions(c, defaults, projectIdentity) {
-  const params = searchParams(c);
-  const limitValue = parseNumberParam(params.get("limit") ?? void 0);
-  return {
-    agent: optionalQueryValue(params.get("agent") ?? void 0),
-    project: optionalQueryValue(params.get("project") ?? void 0),
-    projectKind: projectIdentity?.kind,
-    projectKey: projectIdentity?.key,
-    cwd: optionalQueryValue(params.get("cwd") ?? void 0),
-    tags: parseSmartTags(queryValues(params, "tag", "tags", "signal")),
-    tools: queryValues(params, "tool", "tools").map((tool) => tool.toLowerCase()),
-    file: optionalQueryValue(params.get("file") ?? params.get("path") ?? void 0),
-    fileKind: parseFileActivityKind(
-      optionalQueryValue(params.get("fileKind") ?? params.get("fileActivity") ?? void 0)
-    ),
-    costMin: parseNumberParam(params.get("costMin") ?? void 0),
-    costMax: parseNumberParam(params.get("costMax") ?? void 0),
-    from: parseDateParam(params.get("from") ?? void 0, defaults.from),
-    to: parseDateParam(params.get("to") ?? void 0, defaults.to),
-    limit: limitValue && limitValue > 0 ? Math.min(limitValue, 100) : 50
-  };
+function parseSessionReferencePayload(value) {
+  if (!isRecord(value) || typeof value.agentName !== "string" || typeof value.sessionId !== "string" || !value.agentName.trim() || !value.sessionId) {
+    return null;
+  }
+  return normalizeSessionReference({
+    agentName: value.agentName.trim().toLowerCase(),
+    sessionId: value.sessionId
+  });
 }
-function filterSessionsByActivityWindow(sessions, from, to) {
-  if (from == null && to == null) return sessions;
-  return sessions.filter((session) => {
-    const activity = getSessionActivityTime(session);
-    if (from != null && activity < from) return false;
-    if (to != null && activity > to) return false;
-    return true;
+function parseBookmarkPayload(value) {
+  if (!isRecord(value)) return null;
+  const reference = parseSessionReferencePayload(value.reference);
+  if (reference) {
+    const session2 = parseBookmarkSession(value.session, reference);
+    return session2 ? { reference, session: session2 } : null;
+  }
+  if (typeof value.agentKey !== "string" || typeof value.sessionId !== "string" || typeof value.fullPath !== "string" || !value.agentKey.trim() || !value.sessionId) {
+    return null;
+  }
+  const legacyReference = normalizeSessionReference({
+    agentName: value.agentKey.trim().toLowerCase(),
+    sessionId: value.sessionId
   });
+  const session = parseBookmarkSession(
+    {
+      ...value,
+      id: value.sessionId,
+      slug: value.fullPath
+    },
+    legacyReference
+  );
+  return session ? { reference: legacyReference, session } : null;
 }
 function sanitizeClientLogData(value) {
   if (!isRecord(value)) return {};
@@ -306,60 +389,58 @@ function sanitizeClientLogData(value) {
     })
   );
 }
-function getProjectGroupKey(identityKind, identityKey) {
-  return `${identityKind}:${identityKey}`;
-}
-function attachProjectMetrics(projects, sessions) {
-  const metrics = /* @__PURE__ */ new Map();
-  for (const session of sessions) {
-    const identity = session.project_identity;
-    if (!identity) continue;
-    const key = getProjectGroupKey(identity.kind, identity.key);
-    let current = metrics.get(key);
-    if (!current) {
-      current = {
-        messages: 0,
-        tokens: 0,
-        cost: 0,
-        hasEstimatedCost: false,
-        agentStats: /* @__PURE__ */ new Map()
-      };
-      metrics.set(key, current);
-    }
-    const tokens = getTotalTokens(session.stats);
-    const cost = session.stats.total_cost ?? 0;
-    current.messages += session.stats.message_count;
-    current.tokens += tokens;
-    current.cost += cost;
-    if (session.stats.cost_source === "estimated") current.hasEstimatedCost = true;
-    const agentName = getSessionAgentName(session);
-    const agent = current.agentStats.get(agentName);
-    if (agent) {
-      agent.sessions += 1;
-      agent.messages += session.stats.message_count;
-      agent.tokens += tokens;
-      agent.cost += cost;
-    } else {
-      current.agentStats.set(agentName, {
-        name: agentName,
-        sessions: 1,
-        messages: session.stats.message_count,
-        tokens,
-        cost
-      });
-    }
-  }
-  return projects.map((project) => {
-    const metric = metrics.get(getProjectGroupKey(project.identityKind, project.identityKey));
-    return {
-      ...project,
-      messages: metric?.messages ?? 0,
-      tokens: metric?.tokens ?? 0,
-      cost: metric?.cost ?? 0,
-      cost_source: metric && metric.cost > 0 ? metric.hasEstimatedCost ? "estimated" : "recorded" : void 0,
-      agentStats: [...metric?.agentStats.values() ?? []].sort((a, b) => b.sessions - a.sessions)
-    };
-  });
+function toSessionListItem(session) {
+  if (!session.model_usage) return session;
+  const item = { ...session };
+  delete item.model_usage;
+  return item;
+}
+function getSessionHeadReference(session) {
+  return {
+    agentName: getSessionAgentKey(session),
+    sessionId: session.id
+  };
+}
+var SESSION_DETAIL_STREAM_BATCH_CHARS = 64 * 1024;
+function createSessionDetailJsonResponse(data, messages) {
+  const encoder = new TextEncoder();
+  const headerJson = JSON.stringify(data);
+  const iterator = messages[Symbol.iterator]();
+  let wroteHeader = false;
+  let wroteMessage = false;
+  return new Response(
+    new ReadableStream({
+      pull(controller) {
+        if (!wroteHeader) {
+          controller.enqueue(encoder.encode(`${headerJson.slice(0, -1)},"messages":[`));
+          wroteHeader = true;
+          return;
+        }
+        const batch = [];
+        let batchLength = 0;
+        let next = iterator.next();
+        while (!next.done) {
+          const prefix = wroteMessage ? "," : "";
+          batch.push(prefix, next.value);
+          batchLength += prefix.length + next.value.length;
+          wroteMessage = true;
+          if (batchLength >= SESSION_DETAIL_STREAM_BATCH_CHARS) break;
+          next = iterator.next();
+        }
+        if (next.done) {
+          batch.push("]}");
+          controller.enqueue(encoder.encode(batch.join("")));
+          controller.close();
+          return;
+        }
+        controller.enqueue(encoder.encode(batch.join("")));
+      },
+      cancel() {
+        iterator.return?.();
+      }
+    }),
+    { headers: { "Content-Type": "application/json; charset=UTF-8" } }
+  );
 }
 function handleGetConfig(c, defaults) {
   const payload = {
@@ -378,22 +459,38 @@ function handleGetAgents(c, scanSource, defaults = {}) {
   const scanResult = scanSource.getSnapshot();
   const from = parseDateParam(c.req.query("from"), defaults.from);
   const to = parseDateParam(c.req.query("to"), defaults.to);
-  const counts = Object.fromEntries(
-    Object.entries(scanResult.byAgent).map(([agentName, sessions]) => [
-      agentName,
-      filterSessionsByActivityWindow(sessions, from, to).length
-    ])
+  const agents = getSnapshotAggregation(
+    scanSource,
+    scanResult.sessions,
+    ["agents", from, to],
+    () => {
+      const counts = Object.fromEntries(
+        Object.entries(scanResult.byAgent).map(([agentName, sessions]) => [
+          agentName,
+          filterSessionsByActivityWindow(sessions, from, to).length
+        ])
+      );
+      return getAgentInfoMap(counts);
+    }
   );
-  return c.json(getAgentInfoMap(counts));
+  return c.json(agents);
 }
 function handleGetProjects(c, scanSource, defaults = {}) {
   const scanResult = scanSource.getSnapshot();
   const from = parseDateParam(c.req.query("from"), defaults.from);
   const to = parseDateParam(c.req.query("to"), defaults.to);
-  const sessions = filterSessionsByActivityWindow(scanResult.sessions, from, to);
-  return c.json({
-    projects: attachProjectMetrics(listCachedProjectGroups(sessions), sessions)
-  });
+  const projects = getSnapshotAggregation(
+    scanSource,
+    scanResult.sessions,
+    ["projects", from, to],
+    () => {
+      const sessions = filterSessionsByActivityWindow(scanResult.sessions, from, to);
+      return {
+        projects: attachProjectMetrics(listCachedProjectGroups(sessions), sessions)
+      };
+    }
+  );
+  return c.json(projects);
 }
 function handleGetSessions(c, scanSource, defaults = {}) {
   const scanResult = scanSource.getSnapshot();
@@ -428,16 +525,16 @@ function handleGetSessions(c, scanSource, defaults = {}) {
   if (tag) {
     sessions = sessions.filter((s) => s.smart_tags?.includes(tag));
   }
-  const aliases = loadSessionAliasMap();
+  const aliases = loadAliasView();
   if (q) {
     sessions = sessions.filter((session) => {
-      const alias = aliases.get(getSessionAliasKey(getSessionAgentKey(session), session.id));
+      const alias = aliases.get(getSessionHeadReference(session));
       return session.title.toLowerCase().includes(q) || alias?.toLowerCase().includes(q);
     });
   }
   return c.json({
     sessions: sessions.map(
-      (session) => withDisplayTitle(session, getSessionAgentKey(session), aliases)
+      (session) => toSessionListItem(aliases.decorate(session, getSessionHeadReference(session)))
     )
   });
 }
@@ -452,35 +549,18 @@ function handleSearchSessions(c, scanSource, defaults = {}) {
     return c.json({ error: "projectKind and projectKey must form a valid project identity" }, 400);
   }
   const searchOptions = parseSearchOptions(c, defaults, projectIdentity);
-  const aliases = loadSessionAliasMap();
+  const aliases = loadAliasView();
   const results = executeSessionSearch(query, searchOptions, scanResult).map((result) => ({
     ...result,
-    session: withDisplayTitle(result.session, result.agentName, aliases)
+    session: aliases.decorate(result.session, result.reference)
   }));
   const aliasResults = findAliasSearchResults(query, searchOptions, scanResult, aliases);
   const deduped = /* @__PURE__ */ new Map();
   for (const result of [...aliasResults, ...results]) {
-    deduped.set(`${result.agentName}\0${result.session.id}`, result);
+    deduped.set(`${result.reference.agentName}\0${result.reference.sessionId}`, result);
   }
   return c.json({ results: [...deduped.values()].slice(0, searchOptions.limit ?? 50) });
 }
-function parseFileActivityKind(value) {
-  if (value === "read" || value === "edit" || value === "write" || value === "delete") {
-    return value;
-  }
-  return void 0;
-}
-function optionalQueryValue(value) {
-  const normalized = value?.trim();
-  return normalized ? normalized : void 0;
-}
-function parseProjectIdentityFilter(kindValue, keyValue) {
-  const kind = optionalQueryValue(kindValue);
-  const key = optionalQueryValue(keyValue);
-  if (!kind && !key) return void 0;
-  if (!kind || !key || !isProjectIdentityKind(kind)) return null;
-  return { kind, key };
-}
 function handleGetFileActivity(c, defaults = {}) {
   const limitValue = Number(c.req.query("limit"));
   const limit = Number.isFinite(limitValue) && limitValue > 0 ? Math.min(limitValue, 200) : 50;
@@ -491,7 +571,7 @@ function handleGetFileActivity(c, defaults = {}) {
   if (projectIdentity === null) {
     return c.json({ error: "projectKind and projectKey must form a valid project identity" }, 400);
   }
-  const aliases = loadSessionAliasMap();
+  const aliases = loadAliasView();
   return c.json({
     activity: listFileActivity({
       agent: optionalQueryValue(c.req.query("agent")),
@@ -505,12 +585,11 @@ function handleGetFileActivity(c, defaults = {}) {
       from: parseDateParam(c.req.query("from"), defaults.from),
       to: parseDateParam(c.req.query("to"), defaults.to),
       limit
-    }).map((activity) => withFileActivityDisplayTitle(activity, aliases))
+    }).map((activity) => decorateFileActivity(activity, aliases))
   });
 }
 async function handleGetSessionData(c, scanSource) {
   const startedAt = performance.now();
-  const scanResult = scanSource.getSnapshot();
   const agentName = c.req.param("agent");
   const sessionId = c.req.param("id");
   if (!agentName) {
@@ -519,21 +598,15 @@ async function handleGetSessionData(c, scanSource) {
   if (!sessionId) {
     return c.json({ error: "Missing session ID" }, 400);
   }
-  const agent = scanResult.agents.find((a) => a.name === agentName);
-  if (!agent) {
-    return c.json({ error: `Unknown agent: ${agentName}` }, 404);
-  }
   try {
-    const head = scanResult.byAgent[agentName]?.find((item) => item.id === sessionId);
-    const loadStartedAt = performance.now();
-    const cachedEntry = loadCachedSessionDataEntry(agentName, sessionId);
-    const cachedData = cachedEntry?.data ?? null;
-    const cachedMessageCount = cachedData?.stats.message_count ?? 0;
-    const currentMeta = head ? agent.getSessionMetaMap().get(sessionId) : void 0;
-    const cacheHasExpectedMessages = cachedData !== null && cacheMatchesCurrentSource(cachedEntry?.meta ?? null, currentMeta) && (cachedData.messages.length > 0 || cachedMessageCount === 0);
-    const data = cacheHasExpectedMessages ? cachedData : head ? agent.getSessionData(sessionId) : null;
-    const loadDuration = performance.now() - loadStartedAt;
-    if (!data) {
+    const result = materializeSessionDetailResponse(scanSource.getSnapshot(), {
+      agentName,
+      sessionId
+    });
+    if (result.status === "unknown-agent") {
+      return c.json({ error: `Unknown agent: ${agentName}` }, 404);
+    }
+    if (result.status === "not-ready") {
       appLogger.warn("api.session_data.cache_miss", {
         agent: agentName,
         session_id: sessionId,
@@ -541,27 +614,20 @@ async function handleGetSessionData(c, scanSource) {
       });
       return c.json({ error: "Session cache not ready" }, 404);
     }
-    const tagStartedAt = performance.now();
-    const smartTags = data.smart_tags ?? classifySessionTags(data);
-    const tagDuration = performance.now() - tagStartedAt;
-    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,
-      messages: data.messages.length,
-      load_duration_ms: Math.round(loadDuration),
-      tag_duration_ms: Math.round(tagDuration),
+      messages: result.status === "found-json" ? result.messageCount : result.data.messages.length,
       duration_ms: Math.round(performance.now() - startedAt)
     });
-    const aliases = loadSessionAliasMap();
-    return c.json({
-      ...withDisplayTitle(data, agentName, aliases),
-      project_identity: projectIdentity,
-      smart_tags: smartTags,
-      smart_tags_source_updated_at: getSmartTagSourceTimestamp(data),
-      file_activity: fileActivity
-    });
+    const aliases = loadAliasView();
+    if (result.status === "found-json") {
+      return createSessionDetailJsonResponse(
+        aliases.decorate(result.data, result.data.reference),
+        result.messages
+      );
+    }
+    return c.json(aliases.decorate(result.data, result.data.reference));
   } catch (err) {
     const message = err instanceof Error ? err.message : "Failed to load session";
     appLogger.error("api.session_data.error", {
@@ -584,32 +650,26 @@ async function handlePostClientLog(c) {
   return c.json({ ok: true });
 }
 function handleGetBookmarks(c) {
-  try {
-    const aliases = loadSessionAliasMap();
-    return c.json({
-      bookmarks: listBookmarks().map((bookmark) => withBookmarkDisplayTitle(bookmark, aliases)),
-      storageAvailable: true
-    });
-  } catch (error) {
-    if (error instanceof StateStorageUnavailableError) {
-      return c.json({ bookmarks: [], storageAvailable: false });
-    }
-    throw error;
-  }
+  return withStorageErrors(
+    () => {
+      const aliases = loadAliasView();
+      return c.json({
+        bookmarks: listBookmarks().map((bookmark) => decorateBookmark(bookmark, aliases)),
+        storageAvailable: true
+      });
+    },
+    () => c.json({ bookmarks: [], storageAvailable: false })
+  );
 }
 async function handlePutBookmark(c) {
   const payload = parseBookmarkPayload(await c.req.json().catch(() => null));
   if (!payload) {
     return c.json({ error: "Invalid bookmark payload" }, 400);
   }
-  try {
-    return c.json({ bookmark: upsertBookmark(payload), storageAvailable: true });
-  } catch (error) {
-    if (error instanceof StateStorageUnavailableError) {
-      return c.json({ error: "Bookmark storage is unavailable" }, 503);
-    }
-    throw error;
-  }
+  return withStorageErrors(
+    () => c.json({ bookmark: upsertBookmark(payload), storageAvailable: true }),
+    () => c.json({ error: "Bookmark storage is unavailable" }, 503)
+  );
 }
 async function handleImportBookmarks(c) {
   const payload = await c.req.json().catch(() => null);
@@ -620,14 +680,10 @@ async function handleImportBookmarks(c) {
   if (bookmarks.length !== payload.length) {
     return c.json({ error: "Invalid bookmark payload" }, 400);
   }
-  try {
-    return c.json({ bookmarks: importBookmarks(bookmarks), storageAvailable: true });
-  } catch (error) {
-    if (error instanceof StateStorageUnavailableError) {
-      return c.json({ error: "Bookmark storage is unavailable" }, 503);
-    }
-    throw error;
-  }
+  return withStorageErrors(
+    () => c.json({ bookmarks: importBookmarks(bookmarks), storageAvailable: true }),
+    () => c.json({ error: "Bookmark storage is unavailable" }, 503)
+  );
 }
 function handleDeleteBookmark(c) {
   const agentKey = c.req.param("agent");
@@ -635,32 +691,35 @@ function handleDeleteBookmark(c) {
   if (!agentKey || !sessionId) {
     return c.json({ error: "Missing bookmark identifier" }, 400);
   }
-  try {
-    deleteBookmark(agentKey, sessionId);
-    return c.json({ ok: true, storageAvailable: true });
-  } catch (error) {
-    if (error instanceof StateStorageUnavailableError) {
-      return c.json({ error: "Bookmark storage is unavailable" }, 503);
-    }
-    throw error;
-  }
+  return withStorageErrors(
+    () => {
+      deleteBookmark({ agentName: agentKey, sessionId });
+      return c.json({ ok: true, storageAvailable: true });
+    },
+    () => c.json({ error: "Bookmark storage is unavailable" }, 503)
+  );
 }
 async function handlePutSessionAlias(c) {
   const agentKey = c.req.param("agent");
   const sessionId = c.req.param("id");
   const payload = await c.req.json().catch(() => null);
-  if (!agentKey || !sessionId || typeof payload?.alias !== "string") {
+  const aliasValue = payload?.alias;
+  if (!agentKey || !sessionId || typeof aliasValue !== "string") {
     return c.json({ error: "Invalid session alias payload" }, 400);
   }
   try {
-    return c.json({ alias: upsertSessionAlias(agentKey, sessionId, payload.alias) });
+    return withStorageErrors(
+      () => {
+        const alias = upsertSessionAlias({ agentName: agentKey, sessionId }, aliasValue);
+        invalidateAliasView();
+        return c.json({ alias });
+      },
+      () => c.json({ error: "Session alias storage is unavailable" }, 503)
+    );
   } catch (error) {
-    if (error instanceof TypeError) {
+    if (error instanceof SessionAliasValidationError) {
       return c.json({ error: "Session alias must be non-empty and at most 160 characters" }, 400);
     }
-    if (isStateStorageUnavailable(error)) {
-      return c.json({ error: "Session alias storage is unavailable" }, 503);
-    }
     throw error;
   }
 }
@@ -670,15 +729,14 @@ function handleDeleteSessionAlias(c) {
   if (!agentKey || !sessionId) {
     return c.json({ error: "Missing session alias identifier" }, 400);
   }
-  try {
-    deleteSessionAlias(agentKey, sessionId);
-    return c.json({ ok: true });
-  } catch (error) {
-    if (isStateStorageUnavailable(error)) {
-      return c.json({ error: "Session alias storage is unavailable" }, 503);
-    }
-    throw error;
-  }
+  return withStorageErrors(
+    () => {
+      deleteSessionAlias({ agentName: agentKey, sessionId });
+      invalidateAliasView();
+      return c.json({ ok: true });
+    },
+    () => c.json({ error: "Session alias storage is unavailable" }, 503)
+  );
 }
 function handleGetDashboard(c, scanSource, defaults = {}) {
   const scanResult = scanSource.getSnapshot();
@@ -703,15 +761,30 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
     projectKind: projectIdentity?.kind,
     projectKey: projectIdentity?.key
   };
-  const agentInfo = getAgentInfoMap({});
-  const agentInfoMap = new Map(agentInfo.map((a) => [a.name, a]));
-  const aggregate = buildDashboard(scanResult.sessions, {
-    byAgentNames: Object.keys(scanResult.byAgent),
-    scope,
-    from,
-    to,
-    agentInfoMap
-  });
+  const fixedTo = parseDateParam(c.req.query("to"), defaults.to);
+  const aggregate = getSnapshotAggregation(
+    scanSource,
+    scanResult.sessions,
+    [
+      "dashboard",
+      scope.agent,
+      scope.projectKind,
+      scope.projectKey,
+      from,
+      fixedTo ?? startOfCalendarDay(to)
+    ],
+    () => {
+      const agentInfo = getAgentInfoMap({});
+      const agentInfoMap = new Map(agentInfo.map((agent) => [agent.name, agent]));
+      return buildDashboard(scanResult.sessions, {
+        byAgentNames: Object.keys(scanResult.byAgent),
+        scope,
+        from,
+        to,
+        agentInfoMap
+      });
+    }
+  );
   const data = {
     ...aggregate,
     recentFileActivities: listFileActivity({
@@ -724,14 +797,15 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
     }),
     window: { from, to, days }
   };
-  const aliases = loadSessionAliasMap();
+  const aliases = loadAliasView();
   return c.json({
     ...data,
-    recentSessions: data.recentSessions.map(
-      (session) => withDisplayTitle(session, session.agentName, aliases)
-    ),
+    recentSessions: data.recentSessions.map((item) => ({
+      ...item,
+      session: aliases.decorate(item.session, item.reference)
+    })),
     recentFileActivities: data.recentFileActivities.map(
-      (activity) => withFileActivityDisplayTitle(activity, aliases)
+      (activity) => decorateFileActivity(activity, aliases)
     )
   });
 }
@@ -828,8 +902,48 @@ function createApiRoutes(scanSource, eventSource, options = {}) {
 
 // src/remote-access.ts
 import { randomBytes, timingSafeEqual } from "crypto";
+import { readFileSync } from "fs";
 import { isIP } from "net";
 var REMOTE_ACCESS_QUERY_PARAM = "access_token";
+var RemoteTransportError = class extends Error {
+};
+function resolveRemoteTransport(request) {
+  const hasCert = Boolean(request.tlsCertPath);
+  const hasKey = Boolean(request.tlsKeyPath);
+  if (hasCert !== hasKey) {
+    throw new RemoteTransportError("TLS requires both --tls-cert and --tls-key.");
+  }
+  if (hasCert && request.trustProxy) {
+    throw new RemoteTransportError(
+      "Use either --tls-cert/--tls-key or --trust-proxy, not both: only one of them terminates TLS."
+    );
+  }
+  if (hasCert) {
+    try {
+      return {
+        kind: "tls",
+        cert: readFileSync(request.tlsCertPath),
+        key: readFileSync(request.tlsKeyPath)
+      };
+    } catch (error) {
+      throw new RemoteTransportError(
+        `Unable to read the TLS certificate or key: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  if (request.trustProxy) return { kind: "trusted-proxy" };
+  return isLoopbackHostname(request.hostname) ? { kind: "loopback" } : { kind: "plaintext" };
+}
+var FORWARDED_PROTO_HEADER = "X-Forwarded-Proto";
+function requireProxyTls() {
+  return async (c, next) => {
+    const proto = c.req.header(FORWARDED_PROTO_HEADER)?.split(",")[0]?.trim().toLowerCase();
+    if (proto !== "https") {
+      return c.json({ error: "Requests must arrive over TLS through the trusted proxy" }, 403);
+    }
+    await next();
+  };
+}
 function createRemoteAccessToken() {
   return randomBytes(32).toString("base64url");
 }
@@ -909,6 +1023,7 @@ async function createServer(port, store, options = {}) {
   const app = new Hono2();
   const hostname = options.hostname ?? "127.0.0.1";
   const isLoopback = isLoopbackHostname(hostname);
+  const transport = options.transport ?? (isLoopback ? { kind: "loopback" } : { kind: "plaintext" });
   const remoteAccessToken = !isLoopback ? options.remoteAccessToken ?? (options.remoteAccess ? createRemoteAccessToken() : null) : null;
   if (!isLoopback && !remoteAccessToken) {
     throw new Error(
@@ -935,6 +1050,9 @@ async function createServer(port, store, options = {}) {
       });
     }
   });
+  if (transport.kind === "trusted-proxy") {
+    app.use("/api/*", requireProxyTls());
+  }
   if (remoteAccessToken) {
     app.use("/api/*", remoteAccessAuth(remoteAccessToken));
   }
@@ -952,7 +1070,7 @@ async function createServer(port, store, options = {}) {
     defaultSessionDays: options.defaultSessionDays
   };
   app.route("/api", createApiRoutes(store, store, routeOptions));
-  const webDistPath = findWebDistPath();
+  const webDistPath = options.webDistPath ?? findWebDistPath();
   if (webDistPath) {
     app.use("/*", serveStatic({ root: webDistPath }));
     app.get("/*", serveStatic({ root: webDistPath, path: "index.html" }));
@@ -962,7 +1080,15 @@ async function createServer(port, store, options = {}) {
   let actualPort = port;
   for (let offset = 0; offset < attempts; offset += 1) {
     const candidatePort = port + offset;
-    server = serve({ fetch: app.fetch, port: candidatePort, hostname });
+    server = serve({
+      fetch: app.fetch,
+      port: candidatePort,
+      hostname,
+      ...transport.kind === "tls" ? {
+        createServer: createHttpsServer,
+        serverOptions: { cert: transport.cert, key: transport.key }
+      } : {}
+    });
     try {
       await waitForListening(server);
       actualPort = getListeningPort(server, candidatePort);
@@ -982,19 +1108,33 @@ async function createServer(port, store, options = {}) {
       throw new Error(getServerStartupErrorMessage(error, candidatePort));
     }
   }
-  const baseUrl = isLoopback ? `http://localhost:${actualPort}` : `http://${hostname}:${actualPort}`;
+  const scheme = transport.kind === "tls" ? "https" : "http";
+  const baseUrl = isLoopback ? `${scheme}://localhost:${actualPort}` : `${scheme}://${hostname}:${actualPort}`;
   const url = remoteAccessToken ? `${baseUrl}/?${REMOTE_ACCESS_QUERY_PARAM}=${encodeURIComponent(remoteAccessToken)}` : baseUrl;
   appLogger.info("server.listen", {
     port: actualPort,
     requested_port: port,
     hostname,
-    remote_access: Boolean(remoteAccessToken)
+    remote_access: Boolean(remoteAccessToken),
+    transport: transport.kind
   });
   if (!isLoopback) {
-    appLogger.warn("server.listen.remote_access", { hostname, port: actualPort });
+    appLogger.warn("server.listen.remote_access", {
+      hostname,
+      port: actualPort,
+      transport: transport.kind
+    });
     console.warn(`
 \u26A0 \u8FDC\u7A0B\u8BBF\u95EE\u5DF2\u542F\u7528\u3002\u4EFB\u4F55\u6301\u6709\u542F\u52A8 URL \u7684\u4EBA\u90FD\u53EF\u4EE5\u8BFB\u53D6\u4F60\u7684 AI \u4F1A\u8BDD\u8BB0\u5F55\u3002
 `);
+    if (transport.kind === "plaintext") {
+      appLogger.warn("server.listen.plaintext", { hostname, port: actualPort });
+      console.warn(
+        `\u26A0 \u4F20\u8F93\u672A\u52A0\u5BC6\u3002\u8BBF\u95EE\u4EE4\u724C\u4E0E\u5B8C\u6574\u4F1A\u8BDD\u5185\u5BB9\u4EE5\u660E\u6587\u7ECF\u8FC7\u7F51\u7EDC\uFF0CURL \u4E2D\u7684\u4EE4\u724C\u8FD8\u53EF\u80FD\u5199\u5165\u4EE3\u7406\u8BBF\u95EE\u65E5\u5FD7\u3002
+  \u4F7F\u7528 --tls-cert/--tls-key \u76F4\u63A5\u542F\u7528 TLS\uFF0C\u6216\u5728\u53D7\u4FE1\u53CD\u5411\u4EE3\u7406\u540E\u4F7F\u7528 --trust-proxy\u3002
+`
+      );
+    }
   }
   return {
     url,
@@ -1016,6 +1156,227 @@ async function createServer(port, store, options = {}) {
 import { existsSync as existsSync4 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
+// src/agent-operation-scheduler.ts
+var PENDING_REFRESH_DELAY_MS = 100;
+var MAX_ADAPTIVE_REFRESH_DELAY_MS = 3e4;
+var ADAPTIVE_REFRESH_DELAY_MULTIPLIER = 4;
+var AgentOperationScheduler = class {
+  constructor(runRefresh) {
+    this.runRefresh = runRefresh;
+  }
+  runRefresh;
+  states = /* @__PURE__ */ new Map();
+  operationGenerations = /* @__PURE__ */ new Map();
+  operationTails = /* @__PURE__ */ new Map();
+  isStopped = false;
+  notify(agentName, delayMs) {
+    if (this.isStopped) return;
+    this.state(agentName).pendingSignalCount += 1;
+    this.schedule(agentName, delayMs);
+  }
+  schedule(agentName, delayMs) {
+    if (this.isStopped) return;
+    const state = this.state(agentName);
+    const adaptiveDelayMs = Math.min(
+      state.lastRefreshDurationMs * ADAPTIVE_REFRESH_DELAY_MULTIPLIER,
+      MAX_ADAPTIVE_REFRESH_DELAY_MS
+    );
+    const effectiveDelayMs = Math.max(delayMs, adaptiveDelayMs);
+    const deadline = Date.now() + effectiveDelayMs;
+    if (state.timer) {
+      if (deadline >= state.timerDeadline) return;
+      clearTimeout(state.timer);
+    }
+    appLogger.debug("scan.refresh.schedule", { agent: agentName, delay_ms: effectiveDelayMs });
+    state.timerDeadline = deadline;
+    state.timer = setTimeout(() => {
+      state.timer = null;
+      state.timerDeadline = 0;
+      void this.refresh(agentName);
+    }, effectiveDelayMs);
+  }
+  async refresh(agentName) {
+    if (this.isStopped) return;
+    const state = this.state(agentName);
+    if (state.isRefreshRunning) {
+      appLogger.debug("scan.refresh.pending", { agent: agentName });
+      state.hasPendingRefresh = true;
+      return;
+    }
+    state.isRefreshRunning = true;
+    try {
+      await this.run(agentName, "refresh", () => this.runRefresh(agentName));
+    } finally {
+      state.isRefreshRunning = false;
+      if (state.hasPendingRefresh && !this.isStopped) {
+        state.hasPendingRefresh = false;
+        this.schedule(agentName, PENDING_REFRESH_DELAY_MS);
+      }
+    }
+  }
+  run(agentName, kind, operation) {
+    const previous = this.operationTails.get(agentName) ?? Promise.resolve();
+    const run = previous.then(async () => {
+      if (this.isStopped) return "skipped";
+      const lifecycle = this.beginOperation(agentName, kind);
+      try {
+        const result = await operation();
+        this.completeOperation(lifecycle, result);
+        return result;
+      } catch (error) {
+        this.completeOperation(lifecycle, "failed");
+        throw error;
+      }
+    });
+    const tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    this.operationTails.set(agentName, tail);
+    void tail.finally(() => {
+      if (this.operationTails.get(agentName) === tail) this.operationTails.delete(agentName);
+    });
+    return run;
+  }
+  takePendingSignalCount(agentName) {
+    const state = this.state(agentName);
+    const count = state.pendingSignalCount;
+    state.pendingSignalCount = 0;
+    return count;
+  }
+  recordRefreshDuration(agentName, durationMs) {
+    this.state(agentName).lastRefreshDurationMs = durationMs;
+  }
+  snapshot() {
+    return {
+      activeOperations: this.operationTails.size,
+      activeRefreshes: [...this.states.values()].filter((state) => state.isRefreshRunning).length
+    };
+  }
+  stop() {
+    this.isStopped = true;
+    for (const state of this.states.values()) {
+      if (state.timer) clearTimeout(state.timer);
+      state.timer = null;
+      state.timerDeadline = 0;
+      state.hasPendingRefresh = false;
+      state.pendingSignalCount = 0;
+    }
+  }
+  async waitForIdle() {
+    await Promise.allSettled(this.operationTails.values());
+  }
+  state(agentName) {
+    const existing = this.states.get(agentName);
+    if (existing) return existing;
+    const state = {
+      timer: null,
+      timerDeadline: 0,
+      isRefreshRunning: false,
+      hasPendingRefresh: false,
+      lastRefreshDurationMs: 0,
+      pendingSignalCount: 0
+    };
+    this.states.set(agentName, state);
+    return state;
+  }
+  beginOperation(agentName, kind) {
+    const generation = (this.operationGenerations.get(agentName) ?? 0) + 1;
+    const startedAt = Date.now();
+    this.operationGenerations.set(agentName, generation);
+    appLogger.info("scan.agent_operation.started", {
+      agent: agentName,
+      operation: kind,
+      generation,
+      started_at: startedAt
+    });
+    return { agentName, kind, generation, startedAt };
+  }
+  completeOperation(lifecycle, result) {
+    const completedAt = Date.now();
+    appLogger.info("scan.agent_operation.completed", {
+      agent: lifecycle.agentName,
+      operation: lifecycle.kind,
+      generation: lifecycle.generation,
+      started_at: lifecycle.startedAt,
+      completed_at: completedAt,
+      duration_ms: completedAt - lifecycle.startedAt,
+      result
+    });
+  }
+};
+
+// src/live-session-index.ts
+var LiveSessionIndex = class {
+  agents = [];
+  agentsByName = /* @__PURE__ */ new Map();
+  byAgent = {};
+  sessions = [];
+  signatureCaches = /* @__PURE__ */ new Map();
+  initialize(snapshot, options = {}) {
+    const agentMap = /* @__PURE__ */ new Map();
+    for (const agent of snapshot.agents) agentMap.set(agent.name, agent);
+    for (const agent of options.registeredAgents ?? []) {
+      if (!agentMap.has(agent.name)) agentMap.set(agent.name, agent);
+    }
+    this.agents = [...agentMap.values()].filter(
+      (agent) => !options.allowedAgents || options.allowedAgents.has(agent.name.toLowerCase())
+    );
+    this.agentsByName = new Map(this.agents.map((agent) => [agent.name, agent]));
+    this.byAgent = Object.fromEntries(
+      this.agents.map((agent) => [agent.name, sortSessions(snapshot.byAgent[agent.name] ?? [])])
+    );
+    this.sessions = mergeSortedSessions(Object.values(this.byAgent));
+    this.signatureCaches.clear();
+  }
+  snapshot() {
+    return {
+      agents: this.agents,
+      byAgent: this.byAgent,
+      sessions: this.sessions
+    };
+  }
+  findAgent(agentName) {
+    return this.agentsByName.get(agentName);
+  }
+  commitAgentSessions(agentName, nextSessions, candidateChangedIds = []) {
+    const previousSessions = this.byAgent[agentName] ?? [];
+    const signatureCache = this.signatureCache(agentName);
+    const { changes, removedSessionIds, counts } = computeSessionDiff(
+      previousSessions,
+      nextSessions,
+      candidateChangedIds,
+      sessionSignature,
+      signatureCache
+    );
+    for (const removedId of removedSessionIds) signatureCache.delete(removedId);
+    this.byAgent[agentName] = sortSessions(nextSessions);
+    this.sessions = mergeSortedSessions(Object.values(this.byAgent));
+    if (counts.new === 0 && counts.updated === 0 && counts.removed === 0) return null;
+    return {
+      type: "sessions-updated",
+      changedAgents: [agentName],
+      newSessions: counts.new,
+      updatedSessions: counts.updated,
+      removedSessions: counts.removed,
+      totalSessions: this.sessions.length,
+      timestamp: Date.now(),
+      changedSessionHeads: changes.map(({ session }) => ({
+        reference: { agentName, sessionId: session.id },
+        session
+      })),
+      removedSessionRefs: removedSessionIds.map((sessionId) => ({ agentName, sessionId }))
+    };
+  }
+  signatureCache(agentName) {
+    const existing = this.signatureCaches.get(agentName);
+    if (existing) return existing;
+    const cache = /* @__PURE__ */ new Map();
+    this.signatureCaches.set(agentName, cache);
+    return cache;
+  }
+};
+
 // src/search-index-job-runner.ts
 import { existsSync as existsSync2 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -1168,7 +1529,6 @@ var SearchIndexJobRunner = class {
   nextBatchId = 1;
   pendingJobs = new PendingSearchIndexJobs();
   isShuttingDown = false;
-  hasCheckedFtsIntegrity = false;
   enqueue(context, jobs) {
     if (jobs.length === 0) return Promise.resolve();
     if (this.isShuttingDown) return Promise.reject(new Error(SHUTDOWN_ERROR_MESSAGE));
@@ -1241,8 +1601,7 @@ var SearchIndexJobRunner = class {
         jobs: batch.jobs,
         agentNames: [],
         sessionsByAgent: {},
-        metaByAgent: {},
-        skipFtsIntegrityCheck: this.hasCheckedFtsIntegrity
+        metaByAgent: {}
       }
     });
     worker.unref();
@@ -1253,12 +1612,27 @@ var SearchIndexJobRunner = class {
         logSearchIndexSync(message.context, message.result);
         return;
       }
+      if (message.type === "persist-failed") {
+        appLogger.error("search_index.persist_failed", {
+          batch_id: batch.id,
+          context: message.context,
+          stage: message.stage,
+          agent: message.agentName,
+          sessions: message.sessions
+        });
+        this.settle(
+          batch,
+          new Error(
+            `Search index worker failed to persist ${message.stage} for ${message.agentName}`
+          )
+        );
+        return;
+      }
       if (message.type !== "done") return;
       appLogger.info(`${message.context}.done`, {
         duration_ms: Math.round(message.durationMs),
         sessions: message.sessions
       });
-      this.hasCheckedFtsIntegrity = true;
       this.settle(batch);
     });
     worker.on("error", (error) => {
@@ -1414,6 +1788,21 @@ var ScanStatusModel = class {
       updatedAt: now
     });
   }
+  indexAgent(agentName) {
+    const status = this.status.agentStatuses[agentName];
+    if (!this.status.active || !status || status.status !== "scanning") return null;
+    const now = Date.now();
+    const agentStatuses = {
+      ...this.status.agentStatuses,
+      [agentName]: { ...status, status: "indexing", updatedAt: now }
+    };
+    return this.set({
+      ...this.status,
+      phase: this.activePhase(this.status.pendingAgents, this.status.scanningAgents, agentStatuses),
+      agentStatuses,
+      updatedAt: now
+    });
+  }
   finishAgent(agentName, sessionCount) {
     const pendingAgents = this.status.pendingAgents.filter((agent) => agent !== agentName);
     const scanningAgents = this.status.scanningAgents.filter((agent) => agent !== agentName);
@@ -1422,26 +1811,27 @@ var ScanStatusModel = class {
     const now = Date.now();
     const previousStatus = this.status.agentStatuses[agentName];
     const total = previousStatus?.total ?? previousStatus?.processed;
+    const agentStatuses = {
+      ...this.status.agentStatuses,
+      [agentName]: {
+        agentName,
+        status: "complete",
+        total,
+        processed: total,
+        sessions: sessionCount ?? previousStatus?.sessions ?? 0,
+        startedAt: previousStatus?.startedAt,
+        updatedAt: now,
+        completedAt: now
+      }
+    };
     return this.set({
       ...this.status,
       active: isActive,
-      phase: isActive ? "scanning" : "idle",
+      phase: isActive ? this.activePhase(pendingAgents, scanningAgents, agentStatuses) : "idle",
       pendingAgents,
       scanningAgents,
       completedAgents,
-      agentStatuses: {
-        ...this.status.agentStatuses,
-        [agentName]: {
-          agentName,
-          status: "complete",
-          total,
-          processed: total,
-          sessions: sessionCount ?? previousStatus?.sessions ?? 0,
-          startedAt: previousStatus?.startedAt,
-          updatedAt: now,
-          completedAt: now
-        }
-      },
+      agentStatuses,
       updatedAt: now,
       completedAt: isActive ? void 0 : now
     });
@@ -1471,6 +1861,12 @@ var ScanStatusModel = class {
       updatedAt: Date.now()
     });
   }
+  activePhase(pendingAgents, scanningAgents, agentStatuses) {
+    if (pendingAgents.length === 0 && scanningAgents.length > 0 && scanningAgents.every((agentName) => agentStatuses[agentName]?.status === "indexing")) {
+      return "indexing";
+    }
+    return this.status.phase === "initializing" ? "initializing" : "scanning";
+  }
   set(status) {
     this.status = status;
     return this.snapshot();
@@ -1480,38 +1876,16 @@ var ScanStatusModel = class {
 // src/agent-sync-engine.ts
 var REFRESH_DEBOUNCE_MS = 200;
 var EMPTY_AGENT_REFRESH_DEBOUNCE_MS = 3e4;
-var PENDING_REFRESH_DELAY_MS = 100;
-var MAX_ADAPTIVE_REFRESH_DELAY_MS = 3e4;
-var ADAPTIVE_REFRESH_DELAY_MULTIPLIER = 4;
 var SEARCH_INDEX_BULK_PENDING_PATH_THRESHOLD = 100;
 var BACKFILL_INTERVAL_MS = 24 * 60 * 60 * 1e3;
-function buildRefreshDiff(agentName, previousSessions, nextSessions, candidateChangedIds = [], signatureCache) {
-  const { changes, removedSessionIds, counts } = computeSessionDiff(
+function buildPersistenceDiff(previousSessions, nextSessions, candidateChangedIds = []) {
+  const { changes, removedSessionIds } = computeSessionDiff(
     previousSessions,
     nextSessions,
     candidateChangedIds,
-    sessionSignature,
-    signatureCache
+    sessionSignature
   );
-  for (const removedId of removedSessionIds) signatureCache?.delete(removedId);
-  if (counts.new === 0 && counts.updated === 0 && counts.removed === 0) {
-    return { event: null, changedSessions: changes, removedSessionIds };
-  }
-  return {
-    changedSessions: changes,
-    removedSessionIds,
-    event: {
-      type: "sessions-updated",
-      changedAgents: [agentName],
-      newSessions: counts.new,
-      updatedSessions: counts.updated,
-      removedSessions: counts.removed,
-      totalSessions: nextSessions.length,
-      timestamp: Date.now(),
-      changedSessionHeads: changes.map(({ session }) => ({ agentName, session })),
-      removedSessionRefs: removedSessionIds.map((sessionId) => ({ agentName, sessionId }))
-    }
-  };
+  return { changedSessions: changes, removedSessionIds };
 }
 function restoreAgentCacheMeta(agent, cached) {
   agent.setSessionMetaMap(new Map(Object.entries(cached.meta)));
@@ -1519,11 +1893,12 @@ function restoreAgentCacheMeta(agent, cached) {
 var AgentSyncEngine = class {
   constructor(options) {
     this.options = options;
+    this.scheduler = new AgentOperationScheduler((agentName) => this.performRefresh(agentName));
   }
-  options;
-  refreshStates = /* @__PURE__ */ new Map();
-  operationGenerations = /* @__PURE__ */ new Map();
-  operationTails = /* @__PURE__ */ new Map();
+  options;
+  lastRefreshAtByAgent = /* @__PURE__ */ new Map();
+  scheduler;
+  sessionIndex = new LiveSessionIndex();
   backfillQueue = [];
   currentBackfillAgent;
   completedBackfillAgents = [];
@@ -1532,13 +1907,22 @@ var AgentSyncEngine = class {
   statusChangedListeners = /* @__PURE__ */ new Set();
   scanStatus = new ScanStatusModel();
   searchIndexJobs = new SearchIndexJobRunner();
+  nextPublicationId = 1;
   backgroundRefreshTimer = null;
   isShuttingDown = false;
-  initialize(cacheTimestamps = {}) {
-    for (const agent of this.options.snapshot().agents) {
-      this.state(agent.name).lastRefreshAt = cacheTimestamps[agent.name] ?? Date.now();
+  initialize(snapshot, options = {}) {
+    this.sessionIndex.initialize(snapshot, options);
+    this.lastRefreshAtByAgent.clear();
+    for (const agent of this.sessionIndex.snapshot().agents) {
+      this.lastRefreshAtByAgent.set(
+        agent.name,
+        options.cacheTimestamps?.[agent.name] ?? Date.now()
+      );
     }
   }
+  snapshot() {
+    return this.sessionIndex.snapshot();
+  }
   status() {
     return this.scanStatus.snapshot();
   }
@@ -1551,49 +1935,45 @@ var AgentSyncEngine = class {
     return () => this.statusChangedListeners.delete(listener);
   }
   async syncInitialIndex() {
-    await this.searchIndexJobs.enqueue(
-      "scan.initial",
-      this.buildFullSearchIndexJobs("scan.initial")
-    );
+    const jobs = this.buildFullSearchIndexJobs("scan.initial");
+    await this.commitSearchIndex("scan.initial", jobs, {
+      publicationId: this.publicationId("scan.initial"),
+      agents: jobs.map((job) => job.agentName)
+    });
   }
   handleAgentsChanged(agentNames) {
-    const snapshot = this.options.snapshot();
+    const snapshot = this.sessionIndex.snapshot();
     for (const agentName of agentNames) {
-      this.state(agentName).pendingPathCount += 1;
       const delayMs = (snapshot.byAgent[agentName]?.length ?? 0) === 0 ? EMPTY_AGENT_REFRESH_DEBOUNCE_MS : REFRESH_DEBOUNCE_MS;
-      this.scheduleRefresh(agentName, delayMs);
+      this.scheduler.notify(agentName, delayMs);
     }
   }
   startBackgroundRefresh() {
     if (this.backgroundRefreshTimer) return;
-    const agentNames = this.options.snapshot().agents.map((agent) => agent.name);
+    const agentNames = this.sessionIndex.snapshot().agents.map((agent) => agent.name);
     this.startScanBatch(agentNames, "scanning");
     this.backgroundRefreshTimer = setTimeout(() => {
       this.backgroundRefreshTimer = null;
-      for (const agentName of agentNames) this.scheduleRefresh(agentName, 0);
+      for (const agentName of agentNames) this.scheduler.schedule(agentName, 0);
       if (agentNames.length === 0) this.finishScanBatch();
     }, 0);
   }
   async refresh(agentName) {
-    await this.runCoalescedRefresh(agentName);
+    await this.scheduler.refresh(agentName);
   }
   async shutdown() {
     this.isShuttingDown = true;
+    const schedulerSnapshot = this.scheduler.snapshot();
     const activeOperations = {
-      agent_operations: this.operationTails.size,
-      refreshes: [...this.refreshStates.values()].filter((state) => state.isRunning).length,
+      agent_operations: schedulerSnapshot.activeOperations,
+      refreshes: schedulerSnapshot.activeRefreshes,
       backfill_running: this.currentBackfillAgent != null || void 0,
       scan_workers: this.options.workerRunner.activeCount
     };
     if (activeOperations.agent_operations > 0 || activeOperations.scan_workers > 0) {
       appLogger.warn("scan.shutdown.active_operations", activeOperations);
     }
-    for (const state of this.refreshStates.values()) {
-      if (!state.timer) continue;
-      clearTimeout(state.timer);
-      state.timer = null;
-      state.timerDeadline = 0;
-    }
+    this.scheduler.stop();
     if (this.backgroundRefreshTimer) {
       clearTimeout(this.backgroundRefreshTimer);
       this.backgroundRefreshTimer = null;
@@ -1607,7 +1987,7 @@ var AgentSyncEngine = class {
     });
     await this.searchIndexJobs.shutdown();
     await this.options.workerRunner.shutdown();
-    await Promise.allSettled(this.operationTails.values());
+    await this.scheduler.waitForIdle();
     const stoppedSearchIndexSnapshot = this.searchIndexJobs.snapshot();
     appLogger.info("search_index.shutdown.completed", {
       active_batch_id: searchIndexSnapshot.activeBatchId,
@@ -1615,7 +1995,7 @@ var AgentSyncEngine = class {
     });
   }
   startScanBatch(agentNames, phase) {
-    const snapshot = this.options.snapshot();
+    const snapshot = this.sessionIndex.snapshot();
     const sessionCounts = Object.fromEntries(
       agentNames.map((agentName) => [agentName, snapshot.byAgent[agentName]?.length ?? 0])
     );
@@ -1625,7 +2005,7 @@ var AgentSyncEngine = class {
     this.publishStatus(this.scanStatus.setPhase(phase));
   }
   beginAgentScan(agentName) {
-    const snapshot = this.options.snapshot();
+    const snapshot = this.sessionIndex.snapshot();
     if (!this.scanStatus.snapshot().active) this.startScanBatch([agentName], "scanning");
     this.publishStatus(
       this.scanStatus.beginAgent(agentName, snapshot.byAgent[agentName]?.length ?? 0)
@@ -1634,8 +2014,11 @@ var AgentSyncEngine = class {
   updateAgentScanProgress(agentName, progress) {
     this.publishStatus(this.scanStatus.updateAgent(agentName, progress));
   }
+  beginAgentIndexing(agentName) {
+    this.publishStatus(this.scanStatus.indexAgent(agentName));
+  }
   finishAgentScan(agentName) {
-    const count = this.options.snapshot().byAgent[agentName]?.length;
+    const count = this.sessionIndex.snapshot().byAgent[agentName]?.length;
     this.publishStatus(this.scanStatus.finishAgent(agentName, count));
   }
   finishScanBatch() {
@@ -1652,44 +2035,6 @@ var AgentSyncEngine = class {
     if (this.isShuttingDown) return;
     for (const listener of this.sessionsChangedListeners) listener(change);
   }
-  scheduleRefresh(agentName, delayMs) {
-    if (this.isShuttingDown) return;
-    const state = this.state(agentName);
-    const adaptiveDelayMs = Math.min(
-      state.lastRefreshDurationMs * ADAPTIVE_REFRESH_DELAY_MULTIPLIER,
-      MAX_ADAPTIVE_REFRESH_DELAY_MS
-    );
-    const effectiveDelayMs = Math.max(delayMs, adaptiveDelayMs);
-    const deadline = Date.now() + effectiveDelayMs;
-    if (state.timer) {
-      if (deadline >= state.timerDeadline) return;
-      clearTimeout(state.timer);
-    }
-    appLogger.debug("scan.refresh.schedule", { agent: agentName, delay_ms: effectiveDelayMs });
-    state.timerDeadline = deadline;
-    state.timer = setTimeout(() => {
-      state.timer = null;
-      void this.runCoalescedRefresh(agentName);
-    }, effectiveDelayMs);
-  }
-  async runCoalescedRefresh(agentName) {
-    const state = this.state(agentName);
-    if (state.isRunning) {
-      appLogger.debug("scan.refresh.pending", { agent: agentName });
-      state.hasPendingRerun = true;
-      return;
-    }
-    state.isRunning = true;
-    try {
-      await this.serialize(agentName, "refresh", () => this.performRefresh(agentName));
-    } finally {
-      state.isRunning = false;
-      if (state.hasPendingRerun && !this.isShuttingDown) {
-        state.hasPendingRerun = false;
-        this.scheduleRefresh(agentName, PENDING_REFRESH_DELAY_MS);
-      }
-    }
-  }
   async performRefresh(agentName) {
     this.beginAgentScan(agentName);
     try {
@@ -1706,18 +2051,16 @@ var AgentSyncEngine = class {
   }
   async runRefresh(agentName) {
     const startedAt = performance.now();
-    const state = this.state(agentName);
-    const pendingPathCount = state.pendingPathCount;
-    state.pendingPathCount = 0;
+    const pendingPathCount = this.scheduler.takePendingSignalCount(agentName);
     const agent = this.findAgent(agentName);
     if (!agent) {
       appLogger.warn("scan.refresh.missing_agent", { agent: agentName });
       return "skipped";
     }
-    const previousSessions = this.options.snapshot().byAgent[agentName] ?? [];
+    const previousSessions = this.sessionIndex.snapshot().byAgent[agentName] ?? [];
     const cached = loadCachedSessions(agentName);
     const refreshBaseline = cached?.sessions ?? previousSessions;
-    const cacheTimestamp = cached?.timestamp ?? state.lastRefreshAt;
+    const cacheTimestamp = cached?.timestamp ?? this.lastRefreshAtByAgent.get(agentName) ?? 0;
     if (cached) restoreAgentCacheMeta(agent, cached);
     const isInitialized = isAgentCacheInitialized(agentName);
     const availabilityStartedAt = performance.now();
@@ -1742,74 +2085,73 @@ var AgentSyncEngine = class {
     }
     if (strategyResult.status === "unchanged") return "unchanged";
     const nextSessions = attachMissingProjectIdentities(strategyResult.nextSessions);
-    const diffStartedAt = performance.now();
-    const diff = buildRefreshDiff(
-      agentName,
-      previousSessions,
-      nextSessions,
-      strategyResult.preciseChangedIds ?? [],
-      state.signatureCache
-    );
-    const diffDuration = performance.now() - diffStartedAt;
     const searchIndexOptions = pendingPathCount >= SEARCH_INDEX_BULK_PENDING_PATH_THRESHOLD ? { isBulk: true } : void 0;
-    const persistentChanges = strategyResult.persistenceDiff?.changedSessions ?? diff.changedSessions;
-    const persistentRemovedSessionIds = strategyResult.persistenceDiff?.removedSessionIds ?? diff.removedSessionIds;
-    const changedSessionIds = strategyResult.usedIncrementalScan ? new Set(persistentChanges.map(({ session }) => session.id)) : void 0;
+    const persistenceDiff = strategyResult.persistenceDiff;
+    const changedSessionIds = persistenceDiff ? new Set(persistenceDiff.changedSessions.map(({ session }) => session.id)) : void 0;
     const persistStartedAt = performance.now();
-    const persistentJob = strategyResult.usedIncrementalScan ? {
+    const persistentJob = persistenceDiff ? {
       kind: "changes",
       context: "scan.refresh",
       agentName,
-      changes: persistentChanges,
-      removedSessionIds: persistentRemovedSessionIds,
+      changes: persistenceDiff.changedSessions,
+      removedSessionIds: persistenceDiff.removedSessionIds,
       meta: buildAgentCacheMeta(agent, changedSessionIds),
       ...searchIndexOptions ? { searchIndexOptions } : {}
-    } : strategyResult.fullScanSessions ? {
+    } : {
       kind: "full",
       context: "scan.refresh",
       agentName,
-      sessions: strategyResult.fullScanSessions,
+      sessions: strategyResult.fullScanSessions ?? nextSessions,
       meta: buildAgentCacheMeta(agent),
       saveCache: true,
       ...searchIndexOptions ? { searchIndexOptions } : {}
-    } : null;
-    if (persistentJob) {
-      const persist = this.searchIndexJobs.enqueue("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);
-        });
-      }
-    }
+    };
+    this.beginAgentIndexing(agentName);
+    const publication = await this.commitSessionPublication({
+      context: "scan.refresh",
+      agentName,
+      sessions: nextSessions,
+      candidateChangedIds: strategyResult.preciseChangedIds ?? [],
+      indexJob: persistentJob
+    });
     const persistDuration = performance.now() - persistStartedAt;
     logSearchIndexSync("scan.refresh", null, { pending_paths: pendingPathCount });
-    this.emitSessionsChanged({ agentName, sessions: nextSessions, event: diff.event });
     const totalDurationMs = performance.now() - startedAt;
-    state.lastRefreshDurationMs = totalDurationMs;
+    this.scheduler.recordRefreshDuration(agentName, totalDurationMs);
     appLogger.info("scan.refresh.done", {
       agent: agentName,
       duration_ms: Math.round(totalDurationMs),
       sessions: nextSessions.length,
-      new_sessions: diff.event?.newSessions ?? 0,
-      updated_sessions: diff.event?.updatedSessions ?? 0,
-      removed_sessions: diff.event?.removedSessions ?? 0,
+      new_sessions: publication.event?.newSessions ?? 0,
+      updated_sessions: publication.event?.updatedSessions ?? 0,
+      removed_sessions: publication.event?.removedSessions ?? 0,
       pending_paths: pendingPathCount,
       availability_ms: Math.round(availabilityDuration),
       check_ms: Math.round(strategyResult.checkDuration),
       scan_ms: Math.round(strategyResult.scanDuration),
-      diff_ms: Math.round(diffDuration),
+      diff_ms: Math.round(publication.diffDuration),
       persist_ms: Math.round(persistDuration),
-      search_index_ms: 0,
-      persistent_index_worker_job: persistentJob?.kind,
-      persistent_index_skipped: !persistentJob || void 0
+      search_index_ms: Math.round(persistDuration),
+      persistent_index_worker_job: persistentJob.kind
     });
     return "committed";
   }
+  /**
+   * An agent that cannot be reached was never scanned, so there is nothing to
+   * compare against. Publishing an empty result here would diff every known
+   * session into a removal — the same mistake as reading a failed query as an
+   * empty database.
+   */
   refreshUnavailableAgent(agentName) {
-    this.state(agentName).lastRefreshAt = Date.now();
+    this.lastRefreshAtByAgent.set(agentName, Date.now());
+    const previousSessions = this.sessionIndex.snapshot().byAgent[agentName] ?? [];
+    if (previousSessions.length > 0) {
+      appLogger.warn("scan.refresh.agent_unavailable", {
+        agent: agentName,
+        retained_sessions: previousSessions.length
+      });
+      return this.refreshStrategyResult(previousSessions, { status: "unchanged" });
+    }
     return this.refreshStrategyResult([]);
   }
   async initializeAgent(agent, previousSessions) {
@@ -1818,7 +2160,7 @@ var AgentSyncEngine = class {
     const result = await this.runWorker(agent, previousSessions, null, this.startupScanOptions());
     agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
     const sessions = attachMissingProjectIdentities(result.sessions);
-    this.state(agent.name).lastRefreshAt = Date.now();
+    this.lastRefreshAtByAgent.set(agent.name, Date.now());
     return this.refreshStrategyResult(sessions, {
       fullScanSessions: sessions,
       scanDuration: performance.now() - scanStartedAt
@@ -1833,17 +2175,17 @@ var AgentSyncEngine = class {
     agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
     const sessions = attachMissingProjectIdentities(result.sessions);
     const preciseChangedIds = result.changedIds ?? [];
-    const persistenceDiff = buildRefreshDiff(
-      agent.name,
-      cached.sessions,
-      sessions,
-      preciseChangedIds
-    );
-    this.state(agent.name).lastRefreshAt = Date.now();
-    if (preciseChangedIds.length === 0) this.logUnchangedRefresh(agent.name, refreshStartedAt);
+    const persistenceDiff = buildPersistenceDiff(cached.sessions, sessions, preciseChangedIds);
+    this.lastRefreshAtByAgent.set(agent.name, Date.now());
+    if (persistenceDiff.changedSessions.length === 0 && persistenceDiff.removedSessionIds.length === 0) {
+      this.logUnchangedRefresh(agent.name, refreshStartedAt);
+      return this.refreshStrategyResult(sessions, {
+        status: "unchanged",
+        scanDuration: performance.now() - scanStartedAt
+      });
+    }
     return this.refreshStrategyResult(sessions, {
       preciseChangedIds,
-      usedIncrementalScan: true,
       persistenceDiff,
       scanDuration: performance.now() - scanStartedAt
     });
@@ -1852,22 +2194,29 @@ var AgentSyncEngine = class {
     const checkStartedAt = performance.now();
     const checkResult = await Promise.resolve(agent.checkForChanges(cacheTimestamp, baseline));
     const checkDuration = performance.now() - checkStartedAt;
-    this.state(agent.name).lastRefreshAt = checkResult.timestamp;
+    this.lastRefreshAtByAgent.set(agent.name, checkResult.timestamp);
     if (!checkResult.hasChanges) {
       this.logUnchangedRefresh(agent.name, refreshStartedAt);
       return this.refreshStrategyResult(baseline, { status: "unchanged", checkDuration });
     }
     const preciseChangedIds = checkResult.changedIds ?? null;
     const scanStartedAt = performance.now();
+    if (preciseChangedIds === null) {
+      const result = await this.runWorker(agent, baseline, null, {});
+      agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
+      const sessions2 = attachMissingProjectIdentities(result.sessions);
+      return this.refreshStrategyResult(sessions2, {
+        persistenceDiff: buildPersistenceDiff(baseline, sessions2),
+        checkDuration,
+        scanDuration: performance.now() - scanStartedAt
+      });
+    }
     const sessions = attachMissingProjectIdentities(
-      await Promise.resolve(
-        agent.incrementalScan(baseline, checkResult.changedIds ?? [], checkResult.refs)
-      )
+      await Promise.resolve(agent.incrementalScan(baseline, preciseChangedIds, checkResult.refs))
     );
     return this.refreshStrategyResult(sessions, {
       preciseChangedIds,
-      usedIncrementalScan: Array.isArray(checkResult.changedIds),
-      persistenceDiff: buildRefreshDiff(agent.name, baseline, sessions, preciseChangedIds ?? []),
+      persistenceDiff: buildPersistenceDiff(baseline, sessions, preciseChangedIds),
       checkDuration,
       scanDuration: performance.now() - scanStartedAt
     });
@@ -1877,7 +2226,7 @@ var AgentSyncEngine = class {
     const result = await this.runWorker(agent, previousSessions, null, {});
     agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
     const sessions = attachMissingProjectIdentities(result.sessions);
-    this.state(agent.name).lastRefreshAt = Date.now();
+    this.lastRefreshAtByAgent.set(agent.name, Date.now());
     return this.refreshStrategyResult(sessions, {
       fullScanSessions: sessions,
       scanDuration: performance.now() - scanStartedAt
@@ -1889,7 +2238,6 @@ var AgentSyncEngine = class {
       nextSessions,
       fullScanSessions: null,
       preciseChangedIds: null,
-      usedIncrementalScan: false,
       persistenceDiff: null,
       checkDuration: 0,
       scanDuration: 0,
@@ -1927,30 +2275,31 @@ var AgentSyncEngine = class {
     if (!agentName) return;
     this.currentBackfillAgent = agentName;
     this.publishBackfillStatus();
-    void this.serialize(agentName, "backfill", () => this.performBackfill(agentName)).then(
-      (result) => {
-        if (this.isShuttingDown) return;
-        this.currentBackfillAgent = void 0;
-        if (result === "committed") {
-          if (!this.completedBackfillAgents.includes(agentName)) {
-            this.completedBackfillAgents.push(agentName);
-          }
-          this.failedBackfillAgents = this.failedBackfillAgents.filter(
-            (failedAgent) => failedAgent !== agentName
-          );
-        } else if (!this.failedBackfillAgents.includes(agentName)) {
-          this.failedBackfillAgents.push(agentName);
+    void this.runBackfill(agentName).then((result) => {
+      if (this.isShuttingDown) return;
+      this.currentBackfillAgent = void 0;
+      if (result === "committed") {
+        if (!this.completedBackfillAgents.includes(agentName)) {
+          this.completedBackfillAgents.push(agentName);
         }
-        this.publishBackfillStatus();
-        this.pumpBackfillQueue();
+        this.failedBackfillAgents = this.failedBackfillAgents.filter(
+          (failedAgent) => failedAgent !== agentName
+        );
+      } else if (!this.failedBackfillAgents.includes(agentName)) {
+        this.failedBackfillAgents.push(agentName);
       }
-    );
+      this.publishBackfillStatus();
+      this.pumpBackfillQueue();
+    });
+  }
+  runBackfill(agentName) {
+    return this.scheduler.run(agentName, "backfill", () => this.performBackfill(agentName));
   }
   async performBackfill(agentName) {
     const startedAt = performance.now();
     const agent = this.findAgent(agentName);
     if (!agent || !agent.isAvailable()) return "skipped";
-    const snapshot = this.options.snapshot();
+    const snapshot = this.sessionIndex.snapshot();
     const cached = loadCachedSessions(agentName);
     const baseline = cached?.sessions ?? snapshot.byAgent[agentName] ?? [];
     const meta = cached?.meta ?? buildAgentCacheMeta(agent);
@@ -1968,14 +2317,12 @@ var AgentSyncEngine = class {
       );
       agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
       const fullSessions = attachMissingProjectIdentities(result.sessions);
-      const diff = buildRefreshDiff(
+      await this.commitSessionPublication({
+        context: "scan.backfill",
         agentName,
-        snapshot.byAgent[agentName] ?? [],
-        fullSessions,
-        result.changedIds ?? []
-      );
-      await this.searchIndexJobs.enqueue("scan.backfill", [
-        {
+        sessions: fullSessions,
+        candidateChangedIds: result.changedIds ?? [],
+        indexJob: {
           kind: "full",
           context: "scan.backfill",
           agentName,
@@ -1983,9 +2330,8 @@ var AgentSyncEngine = class {
           meta: buildAgentCacheMeta(agent),
           saveCache: true
         }
-      ]);
+      });
       markAgentFullSyncCompleted(agentName);
-      this.emitSessionsChanged({ agentName, sessions: fullSessions, event: diff.event });
       appLogger.info("scan.backfill.done", {
         agent: agentName,
         duration_ms: Math.round(performance.now() - startedAt),
@@ -1999,70 +2345,6 @@ var AgentSyncEngine = class {
       return "failed";
     }
   }
-  serialize(agentName, kind, operation) {
-    const previous = this.operationTails.get(agentName) ?? Promise.resolve();
-    const run = previous.then(async () => {
-      if (this.isShuttingDown) return "skipped";
-      const lifecycle = this.beginOperation(agentName, kind);
-      try {
-        const result = await operation();
-        this.completeOperation(lifecycle, result);
-        return result;
-      } catch (error) {
-        this.completeOperation(lifecycle, "failed");
-        throw error;
-      }
-    });
-    const tail = run.then(
-      () => void 0,
-      () => void 0
-    );
-    this.operationTails.set(agentName, tail);
-    void tail.finally(() => {
-      if (this.operationTails.get(agentName) === tail) this.operationTails.delete(agentName);
-    });
-    return run;
-  }
-  state(agentName) {
-    const existing = this.refreshStates.get(agentName);
-    if (existing) return existing;
-    const state = {
-      timer: null,
-      timerDeadline: 0,
-      isRunning: false,
-      hasPendingRerun: false,
-      lastRefreshAt: 0,
-      lastRefreshDurationMs: 0,
-      pendingPathCount: 0,
-      signatureCache: /* @__PURE__ */ new Map()
-    };
-    this.refreshStates.set(agentName, state);
-    return state;
-  }
-  beginOperation(agentName, kind) {
-    const generation = (this.operationGenerations.get(agentName) ?? 0) + 1;
-    const startedAt = Date.now();
-    this.operationGenerations.set(agentName, generation);
-    appLogger.info("scan.agent_operation.started", {
-      agent: agentName,
-      operation: kind,
-      generation,
-      started_at: startedAt
-    });
-    return { agentName, kind, generation, startedAt };
-  }
-  completeOperation(lifecycle, result) {
-    const completedAt = Date.now();
-    appLogger.info("scan.agent_operation.completed", {
-      agent: lifecycle.agentName,
-      operation: lifecycle.kind,
-      generation: lifecycle.generation,
-      started_at: lifecycle.startedAt,
-      completed_at: completedAt,
-      duration_ms: completedAt - lifecycle.startedAt,
-      result
-    });
-  }
   backfillStatus() {
     return {
       active: this.currentBackfillAgent != null || this.backfillQueue.length > 0,
@@ -2073,7 +2355,7 @@ var AgentSyncEngine = class {
     };
   }
   buildFullSearchIndexJobs(context) {
-    const snapshot = this.options.snapshot();
+    const snapshot = this.sessionIndex.snapshot();
     return snapshot.agents.map((agent) => {
       const cached = loadCachedSessions(agent.name);
       return cached ? {
@@ -2091,8 +2373,65 @@ var AgentSyncEngine = class {
       };
     });
   }
+  publicationId(context, agentName) {
+    const id = this.nextPublicationId++;
+    return agentName ? `${context}:${agentName}:${id}` : `${context}:${id}`;
+  }
+  async commitSearchIndex(context, jobs, details) {
+    appLogger.info("session.publication.prepared", {
+      publication_id: details.publicationId,
+      context,
+      agent: details.agent,
+      agents: details.agents,
+      jobs: jobs.length
+    });
+    try {
+      await this.searchIndexJobs.enqueue(context, jobs);
+    } catch (error) {
+      appLogger.error("session.publication.failed", {
+        publication_id: details.publicationId,
+        context,
+        agent: details.agent,
+        stage: "search_index",
+        error
+      });
+      throw error;
+    }
+    appLogger.info("session.publication.index_committed", {
+      publication_id: details.publicationId,
+      context,
+      agent: details.agent
+    });
+  }
+  async commitSessionPublication(publication) {
+    const publicationId = this.publicationId(publication.context, publication.agentName);
+    await this.commitSearchIndex(publication.context, [publication.indexJob], {
+      publicationId,
+      agent: publication.agentName
+    });
+    const diffStartedAt = performance.now();
+    const event = this.sessionIndex.commitAgentSessions(
+      publication.agentName,
+      publication.sessions,
+      publication.candidateChangedIds
+    );
+    const diffDuration = performance.now() - diffStartedAt;
+    this.emitSessionsChanged({
+      agentName: publication.agentName,
+      sessions: this.sessionIndex.snapshot().byAgent[publication.agentName] ?? [],
+      event
+    });
+    appLogger.info("session.publication.published", {
+      publication_id: publicationId,
+      context: publication.context,
+      agent: publication.agentName,
+      sessions: publication.sessions.length,
+      has_event: event != null
+    });
+    return { event, diffDuration };
+  }
   findAgent(agentName) {
-    return this.options.snapshot().agents.find((agent) => agent.name === agentName);
+    return this.sessionIndex.findAgent(agentName);
   }
   startupScanOptions() {
     return this.options.startupScanOptions ?? {};
@@ -2148,8 +2487,12 @@ function isSameOrChildPath(parentPath, childPath) {
   const path = relative(parentPath, childPath);
   return path === "" || !path.startsWith("..") && !isAbsolute(path);
 }
+var SQLITE_SIDECAR_SUFFIXES = ["-wal", "-journal"];
+function isSqliteSidecarOf(changedPath, targetPath) {
+  return SQLITE_SIDECAR_SUFFIXES.some((suffix) => changedPath === `${targetPath}${suffix}`);
+}
 function isRelatedPath(changedPath, targetPath) {
-  return isSameOrChildPath(targetPath, changedPath) || isSameOrChildPath(changedPath, targetPath);
+  return isSameOrChildPath(targetPath, changedPath) || isSameOrChildPath(changedPath, targetPath) || isSqliteSidecarOf(changedPath, targetPath);
 }
 function mergeScopes(target, scopes) {
   for (const scope of scopes) {
@@ -2167,49 +2510,6 @@ function resolveWatchEventPath(watchPath, filename) {
   }
   return isAbsolute(filenameText) ? filenameText : join(watchPath, filenameText);
 }
-function resolveAgentWatchTargets(agentName) {
-  const roots = resolveProviderRoots();
-  const cursorDataPath = getCursorDataPath();
-  switch (agentName) {
-    case "claudecode":
-      return [
-        { root: roots.claudeRoot, path: join(roots.claudeRoot, "projects") },
-        { path: "data/claudecode" }
-      ];
-    case "codex":
-      return [
-        { path: join(roots.codexRoot, "sessions") },
-        { path: join(roots.codexRoot, "session_index.jsonl") }
-      ];
-    case "pi":
-      return [
-        { root: roots.piRoot, path: join(roots.piRoot, "agent", "sessions") },
-        { root: "data/pi", path: "data/pi" }
-      ];
-    case "cursor":
-      return cursorDataPath ? [
-        {
-          root: cursorDataPath,
-          path: join(cursorDataPath, "globalStorage", "state.vscdb")
-        },
-        { root: cursorDataPath, path: join(cursorDataPath, "workspaceStorage") }
-      ] : [];
-    case "kimi":
-      return [
-        { root: roots.kimiRoot, path: join(roots.kimiRoot, "sessions") },
-        { path: "data/kimi" }
-      ];
-    case "opencode":
-      return [
-        { root: roots.opencodeRoot, path: join(roots.opencodeRoot, "opencode.db") },
-        { root: "data/opencode", path: "data/opencode/opencode.db" }
-      ];
-    case "zcode":
-      return roots.zcodeRoot ? [{ root: roots.zcodeRoot, path: join(roots.zcodeRoot, "cli", "db", "db.sqlite") }] : [];
-    default:
-      return [];
-  }
-}
 var SessionWatcher = class {
   watchers = [];
   fallbackWatchScopes = /* @__PURE__ */ new Map();
@@ -2222,16 +2522,24 @@ var SessionWatcher = class {
       this.listeners.delete(cb);
     };
   }
-  /** Begin watching the given agent names' data directories. */
-  start(agentNames) {
+  /** Begin watching the session sources declared by each agent adapter. */
+  start(agents) {
     const scopesByRoot = /* @__PURE__ */ new Map();
-    for (const agentName of agentNames) {
-      const watchTargets = resolveAgentWatchTargets(agentName);
-      if (watchTargets.length === 0) {
-        appLogger.debug("watch.skip", { agent: agentName });
+    for (const agent of agents) {
+      const plan = agent.getSessionWatchPlan();
+      if (plan.status !== "supported") {
+        appLogger.debug("watch.skip", {
+          agent: agent.name,
+          status: plan.status,
+          reason: plan.reason
+        });
+        continue;
+      }
+      if (plan.targets.length === 0) {
+        appLogger.debug("watch.skip", { agent: agent.name, status: plan.status });
         continue;
       }
-      for (const target of watchTargets) {
+      for (const target of plan.targets) {
         const watchRootPath = closestWatchablePath(target.root ?? target.path);
         if (!watchRootPath) continue;
         let rootPath;
@@ -2243,17 +2551,17 @@ var SessionWatcher = class {
         }
         const targetPath = toAbsolutePath(target.path);
         const scopes = scopesByRoot.get(rootPath) ?? [];
-        if (!scopes.some((scope) => scope.agentName === agentName && scope.targetPath === targetPath)) {
-          scopes.push({ agentName, targetPath });
+        if (!scopes.some((scope) => scope.agentName === agent.name && scope.targetPath === targetPath)) {
+          scopes.push({ agentName: agent.name, targetPath });
         }
         scopesByRoot.set(rootPath, scopes);
       }
     }
     for (const [rootPath, scopes] of scopesByRoot.entries()) {
-      const agents = Array.from(new Set(scopes.map((scope) => scope.agentName)));
+      const agents2 = Array.from(new Set(scopes.map((scope) => scope.agentName)));
       appLogger.info("watch.start", {
         root: rootPath,
-        agents,
+        agents: agents2,
         targets: scopes.map((scope) => ({
           agent: scope.agentName,
           path: scope.targetPath
@@ -2425,115 +2733,165 @@ var SessionWatcher = class {
 
 // src/worker-runner.ts
 import { Worker as Worker2 } from "worker_threads";
+var SHUTDOWN_ERROR_MESSAGE2 = "Scan refresh worker shut down";
+function applySessionChanges2(previousSessions, changes, removedSessionIds) {
+  const replacedIds = new Set(removedSessionIds);
+  for (const { session } of changes) replacedIds.add(session.id);
+  const retained = previousSessions.filter((session) => !replacedIds.has(session.id));
+  const next = Array.from({
+    length: retained.length + changes.length
+  });
+  for (const { session, sortIndex } of changes) {
+    if (sortIndex < 0 || sortIndex >= next.length || next[sortIndex]) {
+      throw new Error(`Invalid scan refresh sort index: ${sortIndex}`);
+    }
+    next[sortIndex] = session;
+  }
+  let retainedIndex = 0;
+  for (let index = 0; index < next.length; index += 1) {
+    if (!next[index]) next[index] = retained[retainedIndex++];
+  }
+  if (retainedIndex !== retained.length || next.some((session) => !session)) {
+    throw new Error("Invalid scan refresh delta");
+  }
+  return next;
+}
+function applyMetaChanges(previous, changed, replacedSessionIds) {
+  const next = { ...previous };
+  for (const id of replacedSessionIds) delete next[id];
+  return Object.assign(next, changed);
+}
 var ThreadWorkerRunner = class {
   constructor(workerUrl) {
     this.workerUrl = workerUrl;
   }
   workerUrl;
-  workers = /* @__PURE__ */ new Set();
+  workers = /* @__PURE__ */ new Map();
+  nextRequestId = 1;
+  isShuttingDown = false;
   get activeCount() {
-    return this.workers.size;
+    let count = 0;
+    for (const slot of this.workers.values()) count += slot.pending.size;
+    return count;
   }
   run(agentName, payload) {
+    if (this.isShuttingDown) return Promise.reject(new Error(SHUTDOWN_ERROR_MESSAGE2));
+    const request = {
+      type: "run",
+      requestId: this.nextRequestId++,
+      agentName,
+      previousSessions: payload.previousSessions,
+      changedIds: payload.changedIds,
+      sourceSync: payload.sourceSync,
+      scanOptions: payload.scanOptions,
+      meta: payload.meta
+    };
     return new Promise((resolve4, reject) => {
-      const worker = new Worker2(this.workerUrl, {
-        workerData: {
-          agentName,
-          previousSessions: payload.previousSessions,
-          changedIds: payload.changedIds,
-          sourceSync: payload.sourceSync,
-          scanOptions: payload.scanOptions,
-          meta: payload.meta
-        }
-      });
-      worker.unref();
-      this.workers.add(worker);
-      let settled = false;
-      const finish = (callback, terminate = true) => {
-        if (settled) return;
-        settled = true;
-        this.workers.delete(worker);
-        if (terminate) void worker.terminate();
-        callback();
-      };
-      worker.on("message", (message) => {
-        if (message.type === "progress") {
-          payload.onProgress?.(message.progress);
-          return;
-        }
-        if (message.type === "done") {
-          finish(
-            () => resolve4({
-              sessions: message.sessions,
-              meta: message.meta,
-              changedIds: message.changedIds
-            })
-          );
+      let slot = this.workers.get(agentName);
+      const isNewWorker = !slot;
+      if (!slot) {
+        try {
+          slot = this.createWorker(agentName, request);
+        } catch (error) {
+          reject(error instanceof Error ? error : new Error(String(error)));
           return;
         }
-        finish(() => reject(new Error(message.error)));
-      });
-      worker.once("error", (error) => {
-        finish(() => reject(error));
-      });
-      worker.once("exit", (code) => {
-        if (settled) return;
-        appLogger.warn("scan.refresh_worker.exit_before_done", { agent: agentName, code });
-        finish(
-          () => reject(new Error(`Scan refresh worker exited before completing (code ${code})`)),
-          false
-        );
+      }
+      slot.pending.set(request.requestId, {
+        resolve: resolve4,
+        reject,
+        payload,
+        onProgress: payload.onProgress
       });
+      if (!isNewWorker) {
+        try {
+          slot.worker.postMessage(request);
+        } catch (error) {
+          slot.pending.delete(request.requestId);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        }
+      }
     });
   }
   async shutdown() {
-    const workers = [...this.workers];
-    await Promise.allSettled(workers.map((worker) => worker.terminate()));
+    this.isShuttingDown = true;
+    const slots = [...this.workers.values()];
     this.workers.clear();
+    const shutdownError = new Error(SHUTDOWN_ERROR_MESSAGE2);
+    for (const slot of slots) {
+      slot.closed = true;
+      for (const pending of slot.pending.values()) pending.reject(shutdownError);
+      slot.pending.clear();
+    }
+    await Promise.allSettled(slots.map((slot) => slot.worker.terminate()));
+  }
+  createWorker(agentName, request) {
+    const worker = new Worker2(this.workerUrl, { workerData: request });
+    const slot = { worker, pending: /* @__PURE__ */ new Map(), closed: false };
+    worker.unref();
+    this.workers.set(agentName, slot);
+    worker.on("message", (message) => {
+      this.handleMessage(slot, message);
+    });
+    worker.on("error", (error) => {
+      this.closeWorker(agentName, slot, error);
+    });
+    worker.on("exit", (code) => {
+      if (slot.closed) return;
+      const error = new Error(`Scan refresh worker exited before completing (code ${code})`);
+      if (slot.pending.size > 0) {
+        appLogger.warn("scan.refresh_worker.exit_before_done", { agent: agentName, code });
+      }
+      this.closeWorker(agentName, slot, error);
+    });
+    return slot;
+  }
+  handleMessage(slot, message) {
+    const pending = slot.pending.get(message.requestId);
+    if (!pending) return;
+    if (message.type === "progress") {
+      pending.onProgress?.(message.progress);
+      return;
+    }
+    slot.pending.delete(message.requestId);
+    if (message.type === "error") {
+      pending.reject(new Error(message.error));
+      return;
+    }
+    const changedIds = message.changes.map(({ session }) => session.id);
+    const replacedSessionIds = [...changedIds, ...message.removedSessionIds];
+    const removedMetaIds = [...message.removedSessionIds, ...message.removedMetaIds];
+    try {
+      pending.resolve({
+        sessions: applySessionChanges2(
+          pending.payload.previousSessions,
+          message.changes,
+          message.removedSessionIds
+        ),
+        meta: applyMetaChanges(pending.payload.meta, message.meta, removedMetaIds),
+        changedIds: pending.payload.sourceSync ? replacedSessionIds : void 0
+      });
+    } catch (error) {
+      pending.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  closeWorker(agentName, slot, error) {
+    if (slot.closed) return;
+    slot.closed = true;
+    if (this.workers.get(agentName) === slot) this.workers.delete(agentName);
+    for (const pending of slot.pending.values()) pending.reject(error);
+    slot.pending.clear();
   }
 };
 
 // src/live-scan.ts
 var NEW_SESSION_EVENT_WINDOW_MS = 250;
-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])),
-    newSessions: previous.newSessions + next.newSessions,
-    updatedSessions: previous.updatedSessions + next.updatedSessions,
-    removedSessions: previous.removedSessions + next.removedSessions,
-    totalSessions: next.totalSessions,
-    timestamp: next.timestamp,
-    changedSessionHeads: [...changedSessionHeads.values()],
-    removedSessionRefs: [...removedSessionRefs.values()]
-  };
-}
 var LiveScanStore = class {
   watchEnabled;
   scanOptions;
   startupScanOptions;
   deferInitialRefresh;
   syncEngine;
-  agents = [];
-  byAgent = {};
-  sessions = [];
   listeners = /* @__PURE__ */ new Set();
   watcher = null;
   pendingEvent = null;
@@ -2547,11 +2905,12 @@ var LiveScanStore = class {
     this.deferInitialRefresh = options.deferInitialRefresh === true;
     const workerRunner = options.workerRunner ?? new ThreadWorkerRunner(new URL("./scan-refresh-worker.js", import.meta.url));
     this.syncEngine = new AgentSyncEngine({
-      snapshot: () => this.getSnapshot(),
       startupScanOptions: this.startupScanOptions,
       workerRunner
     });
-    this.syncEngine.subscribeSessionsChanged((change) => this.applySessionsChanged(change));
+    this.syncEngine.subscribeSessionsChanged((change) => {
+      if (change.event) this.emit(change.event);
+    });
   }
   async initialize() {
     const startedAt = performance.now();
@@ -2572,18 +2931,26 @@ var LiveScanStore = class {
       smartTagWorkerUrl: this.getSmartTagWorkerUrl() ?? void 0,
       includeSmartTags: this.deferInitialRefresh ? false : void 0
     });
-    this.applyScanResult(initialResult);
-    this.syncEngine.initialize(initialResult.cacheTimestamps);
+    this.syncEngine.initialize(initialResult, {
+      cacheTimestamps: initialResult.cacheTimestamps,
+      registeredAgents: createRegisteredAgents(),
+      allowedAgents: this.getAllowedAgents()
+    });
+    const snapshot = this.getSnapshot();
     const indexStartedAt = performance.now();
-    if (!this.deferInitialRefresh) await this.syncEngine.syncInitialIndex();
+    if (!this.deferInitialRefresh) {
+      await this.syncEngine.syncInitialIndex().catch((error) => {
+        appLogger.error("scan.initial.index_failed", { error });
+      });
+    }
     const indexDuration = performance.now() - indexStartedAt;
     appLogger.info("scan.initial.done", {
       duration_ms: Math.round(performance.now() - startedAt),
       index_ms: this.deferInitialRefresh ? void 0 : Math.round(indexDuration),
       deferred: this.deferInitialRefresh || void 0,
-      sessions: this.sessions.length,
+      sessions: snapshot.sessions.length,
       agents: Object.fromEntries(
-        Object.entries(this.byAgent).map(([key, value]) => [key, value.length])
+        Object.entries(snapshot.byAgent).map(([key, value]) => [key, value.length])
       ),
       agent_timings: initialResult.timings ? Object.fromEntries(
         Object.entries(initialResult.timings).map(([name, timing]) => [
@@ -2602,13 +2969,13 @@ var LiveScanStore = class {
     if (!this.watchEnabled) return;
     this.watcher = new SessionWatcher();
     this.watcher.onAgentsChanged((agentNames) => this.syncEngine.handleAgentsChanged(agentNames));
-    this.watcher.start(this.agents.map((agent) => agent.name));
+    this.watcher.start(snapshot.agents);
   }
   startBackgroundRefresh() {
     this.syncEngine.startBackgroundRefresh();
   }
   getSnapshot() {
-    return { sessions: this.sessions, byAgent: this.byAgent, agents: this.agents };
+    return this.syncEngine.snapshot();
   }
   getScanStatus() {
     return this.syncEngine.status();
@@ -2637,13 +3004,6 @@ var LiveScanStore = class {
       this.watcher = null;
     }
   }
-  applySessionsChanged(change) {
-    this.byAgent[change.agentName] = sortSessions(change.sessions);
-    this.rebuildSessions();
-    if (!change.event) return;
-    change.event.totalSessions = this.sessions.length;
-    this.emit(change.event);
-  }
   emit(event) {
     if (this.shuttingDown) return;
     if (this.pendingEvent || event.newSessions > 0) {
@@ -2656,7 +3016,7 @@ var LiveScanStore = class {
     for (const listener of this.listeners) listener(event);
   }
   queueEvent(event) {
-    this.pendingEvent = this.pendingEvent ? mergeEvents(this.pendingEvent, event) : event;
+    this.pendingEvent = this.pendingEvent ? mergeSessionsUpdatedEvents(this.pendingEvent, event) : event;
     if (this.pendingEventTimer) return;
     this.pendingEventTimer = setTimeout(() => {
       const pending = this.pendingEvent;
@@ -2665,29 +3025,11 @@ var LiveScanStore = class {
       if (pending) this.emitNow(pending);
     }, NEW_SESSION_EVENT_WINDOW_MS);
   }
-  rebuildSessions() {
-    this.sessions = sortSessions(Object.values(this.byAgent).flat());
-  }
   getSmartTagWorkerUrl() {
     const workerUrl = new URL("./smart-tag-worker.js", import.meta.url);
     if (workerUrl.protocol === "file:" && !existsSync4(fileURLToPath3(workerUrl))) return null;
     return workerUrl;
   }
-  applyScanResult(result) {
-    const agentMap = /* @__PURE__ */ new Map();
-    const allowedAgents = this.getAllowedAgents();
-    for (const agent of result.agents) agentMap.set(agent.name, agent);
-    for (const agent of createRegisteredAgents()) {
-      if (!agentMap.has(agent.name)) agentMap.set(agent.name, agent);
-    }
-    this.agents = [...agentMap.values()].filter(
-      (agent) => !allowedAgents || allowedAgents.has(agent.name.toLowerCase())
-    );
-    this.byAgent = Object.fromEntries(
-      this.agents.map((agent) => [agent.name, sortSessions(result.byAgent[agent.name] ?? [])])
-    );
-    this.rebuildSessions();
-  }
   getAllowedAgents() {
     if (!this.scanOptions.agents?.length) return null;
     return new Set(this.scanOptions.agents.map((agent) => agent.toLowerCase()));
@@ -2698,11 +3040,11 @@ var LiveScanStore = class {
 import { consola } from "consola";
 
 // src/version.ts
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 import { resolve as resolve3, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 var __dirname = dirname3(fileURLToPath4(import.meta.url));
-var pkg = JSON.parse(readFileSync(resolve3(__dirname, "../package.json"), "utf-8"));
+var pkg = JSON.parse(readFileSync2(resolve3(__dirname, "../package.json"), "utf-8"));
 var VERSION = pkg.version;
 
 // src/output.ts
@@ -2724,6 +3066,25 @@ function printScanResults(agents) {
   consola.log("");
 }
 
+// src/session-index-output.ts
+function buildSessionIndexOutput(snapshot, window = {}) {
+  const sessions = snapshot.sessions.filter((session) => {
+    const activity = session.time_updated ?? session.time_created;
+    if (window.from != null && activity < window.from) return false;
+    if (window.to != null && activity > window.to) return false;
+    return true;
+  });
+  const agents = getAgentInfoMap(
+    Object.fromEntries(Object.entries(snapshot.byAgent).map(([name, list]) => [name, list.length]))
+  ).map(({ name, displayName, count }) => ({
+    name,
+    displayName,
+    count,
+    available: count > 0
+  }));
+  return { agents, sessions };
+}
+
 // src/runtime-plan.ts
 function parseSessionUri(uri) {
   const match = uri.match(/^([a-z]+):\/\/(.+)$/i);
@@ -2749,7 +3110,10 @@ function buildCliRuntimePlan(input, environment) {
 function resolveStartupUrl(startupUrl, targetSession) {
   if (!targetSession) return startupUrl;
   const url = new URL(startupUrl);
-  url.pathname = `/${targetSession.agent.toLowerCase()}/${targetSession.sessionId}`;
+  url.pathname = sessionRoutePath({
+    agentName: targetSession.agent,
+    sessionId: targetSession.sessionId
+  });
   return url.toString();
 }
 function redactStartupUrl(startupUrl) {
@@ -2774,6 +3138,27 @@ function hasExplicitPortArg(argv) {
   });
 }
 
+// src/pricing-refresh.ts
+var REFRESH_TIMEOUT_MS = 1e4;
+function startPricingRefresh(timeoutMs = REFRESH_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const completion = refreshPricingCache({ signal: controller.signal, timeoutMs }).catch(
+    (error) => {
+      appLogger.warn("pricing.refresh.error", { error });
+      return false;
+    }
+  );
+  return {
+    publish() {
+      if (publishPendingPricing()) appLogger.info("pricing.refresh.published", {});
+    },
+    async cancel() {
+      controller.abort();
+      await completion;
+    }
+  };
+}
+
 // src/index.ts
 var main = defineCommand({
   meta: {
@@ -2798,6 +3183,19 @@ var main = defineCommand({
       description: "Allow authenticated access when binding to a non-loopback address",
       default: false
     },
+    "tls-cert": {
+      type: "string",
+      description: "Path to a TLS certificate; serve remote access over HTTPS"
+    },
+    "tls-key": {
+      type: "string",
+      description: "Path to the TLS private key matching --tls-cert"
+    },
+    "trust-proxy": {
+      type: "boolean",
+      description: "A reverse proxy in front of CodeSesh terminates TLS",
+      default: false
+    },
     agent: {
       type: "string",
       alias: "a",
@@ -2870,6 +3268,18 @@ var main = defineCommand({
       );
       process.exit(1);
     }
+    let transport;
+    try {
+      transport = resolveRemoteTransport({
+        hostname,
+        tlsCertPath: args["tls-cert"],
+        tlsKeyPath: args["tls-key"],
+        trustProxy: args["trust-proxy"]
+      });
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
     if (trace) {
       perf.enable();
     }
@@ -2883,12 +3293,12 @@ var main = defineCommand({
       log_path: appLogger.getLogPath()
     });
     if (clearCache) {
-      const { clearCache: clear } = await import("./dist-AIDCOQZO.js");
+      const { clearCache: clear } = await import("./dist-DMGLFBW6.js");
       clear();
       appLogger.info("cache.clear");
       console.log("Cache cleared.");
     }
-    void refreshPricingCache();
+    const pricingRefresh = startPricingRefresh();
     let targetSession = null;
     if (args.session) {
       targetSession = parseSessionUri(args.session);
@@ -2932,26 +3342,10 @@ var main = defineCommand({
       console.log(perf.getReport());
     }
     if (jsonOnly) {
-      const windowed = result.sessions.filter((s) => {
-        const activity = s.time_updated ?? s.time_created;
-        if (listDefaultFrom != null && activity < listDefaultFrom) return false;
-        if (listDefaultTo != null && activity > listDefaultTo) return false;
-        return true;
-      });
-      const info = getAgentInfoMap(
-        Object.fromEntries(Object.entries(result.byAgent).map(([k, v]) => [k, v.length]))
-      );
-      const output = {
-        agents: info.map(({ name, displayName, count }) => ({
-          name,
-          displayName,
-          count,
-          available: count > 0
-        })),
-        sessions: windowed
-      };
+      await pricingRefresh.cancel();
+      const output = buildSessionIndexOutput(result, { from: listDefaultFrom, to: listDefaultTo });
       appLogger.info("cli.json_output", {
-        sessions: windowed.length,
+        sessions: output.sessions.length,
         duration_ms: Math.round(performance.now() - startedAt)
       });
       console.log(JSON.stringify(output, null, 2));
@@ -2967,7 +3361,8 @@ var main = defineCommand({
         defaultSessionDays: listDefaultDays,
         portFallbackAttempts: explicitPort ? 1 : DEFAULT_PORT_FALLBACK_ATTEMPTS,
         hostname,
-        remoteAccess
+        remoteAccess,
+        transport
       });
     } catch (error) {
       console.error(getServerStartupErrorMessage(error, port));
@@ -2975,6 +3370,7 @@ var main = defineCommand({
     }
     const { url } = app;
     if (!jsonOnly) {
+      pricingRefresh.publish();
       store.startBackgroundRefresh();
     }
     let shuttingDown = false;
@@ -2982,6 +3378,7 @@ var main = defineCommand({
       if (shuttingDown) return;
       shuttingDown = true;
       appLogger.info("cli.shutdown", { signal });
+      await pricingRefresh.cancel();
       await app.shutdown();
       process.exit(0);
     };