codesesh 0.19.0 → 1.0.1

package/dist/index.js

@@ -2,20 +2,24 @@
 import {
   appLogger,
   logSearchIndexSync
-} from "./chunk-KD3DGWZY.js";
+} from "./chunk-OFTTM3UD.js";
 import {
   FileSystemSessionSource,
   SessionAliasValidationError,
   StateStorageUnavailableError,
   addCalendarDays,
   attachMissingProjectIdentities,
-  attachProjectMetrics,
+  attachProjectMetricsFromTree,
   buildAgentCacheMeta,
   buildDashboard,
+  buildSessionTree,
+  closeCacheStorage,
   computeSessionDiff,
   countCalendarDays,
   createProjectScopeMatcher,
   createRegisteredAgents,
+  createSessionIndex,
+  createSessionProjectionContext,
   deleteBookmark,
   deleteSessionAlias,
   executeSessionSearch,
@@ -24,23 +28,25 @@ import {
   formatSessionReference,
   getAgentFullSyncCursor,
   getAgentInfoMap,
-  getAgentLastFullSyncAt,
+  getPricingGeneration,
   getSessionActivityTime,
   getSessionAgentKey,
+  getSessionRouteKey,
   importBookmarks,
-  isAgentCacheInitialized,
   isProjectIdentityKind,
   listBookmarks,
   listCachedProjectGroups,
   listFileActivity,
+  listModelCostDistribution,
   listSessionAliases,
+  loadCachedSessionHeads,
   loadCachedSessions,
-  markAgentCacheInitialized,
   markAgentFullSyncCompleted,
   markAgentFullSyncProgress,
   markAgentFullSyncStarted,
   matchesProjectIdentity,
   matchesProjectScope,
+  materializeBookmarkViews,
   materializeSessionDetailResponse,
   mergeSearchQueryOptions,
   mergeSessionsUpdatedEvents,
@@ -48,9 +54,10 @@ import {
   normalizeSessionReference,
   perf,
   publishPendingPricing,
+  readAgentCacheInitialization,
+  readAgentLastFullSyncAt,
+  readPendingSearchIndexMaintenance,
   refreshPricingCache,
-  saveCachedSessionChanges,
-  saveCachedSessions,
   scanSessions,
   sessionRoutePath,
   sessionSignature,
@@ -58,7 +65,7 @@ import {
   startOfCalendarDay,
   upsertBookmark,
   upsertSessionAlias
-} from "./chunk-G2BTNW3C.js";
+} from "./chunk-JHX5OLL4.js";
 
 // src/index.ts
 import { defineCommand, runMain } from "citty";
@@ -67,6 +74,7 @@ import { defineCommand, runMain } from "citty";
 import { Hono as Hono2 } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { compress } from "hono/compress";
+import { secureHeaders } from "hono/secure-headers";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { existsSync } from "fs";
@@ -149,8 +157,9 @@ var SMART_TAGS = [
   "exploration",
   "planning"
 ];
-var SEARCH_LIMIT_MAX = 100;
-var SEARCH_LIMIT_DEFAULT = 50;
+var SEARCH_LIMIT_POLICY = { defaultValue: 50, maxValue: 100 };
+var FILE_ACTIVITY_LIMIT_POLICY = { defaultValue: 50, maxValue: 200 };
+var SESSION_PAGE_LIMIT_POLICY = { defaultValue: 250, maxValue: 500 };
 function searchParams(c) {
   return new URL(c.req.url ?? "http://localhost/", "http://localhost/").searchParams;
 }
@@ -164,15 +173,51 @@ function optionalQueryValue(value) {
   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;
+  const normalized = optionalQueryValue(value);
+  if (normalized == null) return { kind: "default", value: fallback };
+  const timestamp = new Date(normalized).getTime();
+  return Number.isNaN(timestamp) ? { kind: "invalid", error: "must be a valid date" } : { kind: "valid", value: timestamp };
+}
+function parseDateWindow(params, defaults) {
+  const from = parseDateParam(params.get("from") ?? void 0, defaults.from);
+  if (from.kind === "invalid") return { ...from, parameter: "from" };
+  const to = parseDateParam(params.get("to") ?? void 0, defaults.to);
+  if (to.kind === "invalid") return { ...to, parameter: "to" };
+  if (from.value != null && to.value != null && from.value > to.value) {
+    return { kind: "invalid", parameter: "from", error: "must not be after to" };
+  }
+  return { kind: "valid", from: from.value, to: to.value };
 }
 function parseNumberParam(value) {
   if (value == null || !value.trim()) return void 0;
   const number = Number(value);
   return Number.isFinite(number) ? number : void 0;
 }
+function parseAgentFilter(value, knownAgentNames) {
+  if (value === null) return { kind: "all" };
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return { kind: "unknown" };
+  for (const agentName of knownAgentNames) {
+    if (agentName.toLowerCase() === normalized) return { kind: "known", agentName };
+  }
+  return { kind: "unknown" };
+}
+function parseLimit(value, policy) {
+  if (value === null) return { kind: "default", value: policy.defaultValue };
+  const normalized = value.trim();
+  if (!/^\d+$/.test(normalized)) {
+    return { kind: "invalid", error: "limit must be a positive integer" };
+  }
+  const digits = normalized.replace(/^0+/, "");
+  if (!digits) return { kind: "invalid", error: "limit must be a positive integer" };
+  const maxDigits = String(policy.maxValue);
+  const exceedsMaximum = digits.length > maxDigits.length || digits.length === maxDigits.length && digits > maxDigits;
+  return { kind: "valid", value: exceedsMaximum ? policy.maxValue : Number(digits) };
+}
+function parseSessionQuery(params, knownAgentNames, limitPolicy) {
+  const agent = parseAgentFilter(params.get("agent"), knownAgentNames);
+  return limitPolicy ? { agent, limit: parseLimit(params.get("limit"), limitPolicy) } : { agent };
+}
 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;
@@ -190,11 +235,10 @@ function parseProjectIdentityFilter(kindValue, keyValue) {
   if (!kind || !key || !isProjectIdentityKind(kind)) return null;
   return { kind, key };
 }
-function parseSearchOptions(c, defaults, projectIdentity) {
+function parseSearchOptions(c, window, request, projectIdentity) {
   const params = searchParams(c);
-  const limitValue = parseNumberParam(params.get("limit") ?? void 0);
   return {
-    agent: optionalQueryValue(params.get("agent") ?? void 0),
+    agent: request.agent,
     project: optionalQueryValue(params.get("project") ?? void 0),
     projectKind: projectIdentity?.kind,
     projectKey: projectIdentity?.key,
@@ -207,15 +251,72 @@ function parseSearchOptions(c, defaults, projectIdentity) {
     ),
     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
+    from: window.from,
+    to: window.to,
+    limit: request.limit
   };
 }
 function filterSessionsByActivityWindow(sessions, from, to) {
   return filterSessionTreeByActivityWindow(sessions, from, to);
 }
 
+// src/api/session-pagination.ts
+import { createHash, randomUUID } from "crypto";
+var identityVersions = /* @__PURE__ */ new WeakMap();
+function identityVersion(identity) {
+  const existing = identityVersions.get(identity);
+  if (existing) return existing;
+  const version = randomUUID();
+  identityVersions.set(identity, version);
+  return version;
+}
+function queryFingerprint(params) {
+  const canonical = new URLSearchParams(params);
+  canonical.delete("cursor");
+  canonical.delete("limit");
+  canonical.sort();
+  return createHash("sha256").update(canonical.toString()).digest("base64url");
+}
+function encodeCursor(payload) {
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+function decodeCursor(cursor) {
+  if (!cursor || cursor.length > 512 || !/^[A-Za-z0-9_-]+$/.test(cursor)) return null;
+  try {
+    const value = JSON.parse(
+      Buffer.from(cursor, "base64url").toString("utf8")
+    );
+    if (value.version !== 1 || typeof value.snapshot !== "string" || typeof value.view !== "string" || typeof value.query !== "string" || !Number.isSafeInteger(value.offset) || value.offset <= 0) {
+      return null;
+    }
+    return value;
+  } catch {
+    return null;
+  }
+}
+function paginateSessionSnapshot(items, request) {
+  const snapshot = identityVersion(request.snapshotIdentity);
+  const view = identityVersion(request.viewIdentity);
+  const query = queryFingerprint(request.query);
+  let offset = 0;
+  if (request.cursor) {
+    const cursor = decodeCursor(request.cursor);
+    if (!cursor || cursor.query !== query) return { kind: "invalid_cursor" };
+    if (cursor.snapshot !== snapshot || cursor.view !== view) {
+      return { kind: "stale_snapshot" };
+    }
+    if (cursor.offset >= items.length) return { kind: "invalid_cursor" };
+    offset = cursor.offset;
+  }
+  const end = Math.min(offset + request.limit, items.length);
+  const nextCursor = end < items.length ? encodeCursor({ version: 1, snapshot, view, query, offset: end }) : void 0;
+  return {
+    kind: "page",
+    items: items.slice(offset, end),
+    ...nextCursor ? { nextCursor } : {}
+  };
+}
+
 // src/api/session-aliases-view.ts
 function aliasKey(reference) {
   return `${reference.agentName.toLowerCase()}\0${reference.sessionId}`;
@@ -252,10 +353,14 @@ function invalidateAliasView() {
   cachedView = null;
 }
 function decorateBookmark(bookmark, aliases) {
-  return {
-    ...bookmark,
-    session: aliases.decorate(bookmark.session, bookmark.reference)
-  };
+  if (bookmark.availability === "available") {
+    return {
+      ...bookmark,
+      session: aliases.decorate(bookmark.session, bookmark.reference)
+    };
+  }
+  const displayTitle = aliases.get(bookmark.reference);
+  return displayTitle ? { ...bookmark, display_title: displayTitle } : bookmark;
 }
 function decorateFileActivity(activity, aliases) {
   return {
@@ -286,15 +391,34 @@ function findAliasSearchResults(query, options, scanResult, aliases) {
       reference: alias.reference,
       session: aliases.decorate(session, alias.reference),
       snippet: `Alias \xB7 ${session.directory}`,
+      snippetHighlights: [],
       matchType: "title"
     });
   }
-  return filterSessionSearchCandidates(results, search.options).sort(
+  return filterSessionSearchCandidates(results, search.options, scanResult.sessions).sort(
     (a, b) => getSessionActivityTime(b.session) - getSessionActivityTime(a.session)
   );
 }
 
 // src/api/handlers.ts
+var KNOWN_AGENT_NAMES = getAgentInfoMap({}).map((agent) => agent.name);
+var KNOWN_AGENT_NAME_SET = new Set(KNOWN_AGENT_NAMES);
+function reportInvalidQueryParameter(endpoint, parameter, validationOutcome) {
+  appLogger.warn("api.query_parameter.invalid", {
+    endpoint,
+    parameter,
+    validation_outcome: validationOutcome
+  });
+}
+function parseDateWindowRequest(c, endpoint, defaults) {
+  const outcome = parseDateWindow(searchParams(c), defaults);
+  if (outcome.kind === "valid") return outcome;
+  reportInvalidQueryParameter(endpoint, outcome.parameter, "rejected");
+  return {
+    kind: "rejected",
+    response: c.json({ error: `${outcome.parameter} ${outcome.error}` }, 400)
+  };
+}
 var SNAPSHOT_AGGREGATION_CACHE_LIMIT = 64;
 var snapshotAggregationCaches = /* @__PURE__ */ new WeakMap();
 function getSnapshotAggregation(source, sessions, key, build) {
@@ -326,25 +450,6 @@ function withStorageErrors(handler, onUnavailable) {
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
-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 parseBookmarkSession(value, reference) {
-  if (!isRecord(value)) return null;
-  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 {
-    id: reference.sessionId,
-    slug: formatSessionReference(reference),
-    title: value.title,
-    directory: value.directory,
-    time_created: value.time_created,
-    time_updated: value.time_updated ?? void 0,
-    stats: value.stats
-  };
-}
 function parseSessionReferencePayload(value) {
   if (!isRecord(value) || typeof value.agentName !== "string" || typeof value.sessionId !== "string" || !value.agentName.trim() || !value.sessionId) {
     return null;
@@ -354,29 +459,30 @@ function parseSessionReferencePayload(value) {
     sessionId: value.sessionId
   });
 }
-function parseBookmarkPayload(value) {
+function parseBookmarkReference(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) {
+  if (reference) return reference;
+  if (typeof value.agentKey !== "string" || typeof value.sessionId !== "string" || !value.agentKey.trim() || !value.sessionId) {
     return null;
   }
-  const legacyReference = normalizeSessionReference({
+  return 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 parseBookmarkImport(value) {
+  if (!isRecord(value)) return null;
+  const reference = parseBookmarkReference(value);
+  if (!reference) return null;
+  const timestamp = value.bookmarkedAt ?? value.bookmarked_at;
+  if (timestamp != null && (typeof timestamp !== "number" || !Number.isFinite(timestamp))) {
+    return null;
+  }
+  return {
+    reference,
+    bookmarkedAt: typeof timestamp === "number" ? timestamp : Date.now()
+  };
 }
 function sanitizeClientLogData(value) {
   if (!isRecord(value)) return {};
@@ -391,9 +497,14 @@ function sanitizeClientLogData(value) {
   );
 }
 function toSessionListItem(session) {
-  if (!session.model_usage) return session;
-  const item = { ...session };
-  delete item.model_usage;
+  const {
+    model_usage: _modelUsage,
+    project_identity_resolver_revision: _resolverRevision,
+    project_identity_input_signature: _identityInputSignature,
+    smart_tags_source_updated_at: _smartTagsSourceUpdatedAt,
+    smart_tags_classifier_revision: _smartTagsClassifierRevision,
+    ...item
+  } = session;
   return item;
 }
 function getSessionHeadReference(session) {
@@ -406,6 +517,7 @@ var SESSION_DETAIL_STREAM_BATCH_CHARS = 64 * 1024;
 function createSessionDetailJsonResponse(data, messages) {
   const encoder = new TextEncoder();
   const headerJson = JSON.stringify(data);
+  const headerPrefix = headerJson === "{}" ? '{"messages":[' : `${headerJson.slice(0, -1)},"messages":[`;
   const iterator = messages[Symbol.iterator]();
   let wroteHeader = false;
   let wroteMessage = false;
@@ -413,20 +525,30 @@ function createSessionDetailJsonResponse(data, messages) {
     new ReadableStream({
       pull(controller) {
         if (!wroteHeader) {
-          controller.enqueue(encoder.encode(`${headerJson.slice(0, -1)},"messages":[`));
+          controller.enqueue(encoder.encode(headerPrefix));
           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;
+        let next;
+        try {
           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();
+          }
+        } catch (error) {
+          try {
+            iterator.return?.();
+          } catch {
+          }
+          controller.error(error);
+          return;
         }
         if (next.done) {
           batch.push("]}");
@@ -458,8 +580,9 @@ function handleGetScanStatus(c, scanSource) {
 }
 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 window = parseDateWindowRequest(c, "agents", defaults);
+  if (window.kind === "rejected") return window.response;
+  const { from, to } = window;
   const agents = getSnapshotAggregation(
     scanSource,
     scanResult.sessions,
@@ -478,16 +601,18 @@ function handleGetAgents(c, scanSource, defaults = {}) {
 }
 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 window = parseDateWindowRequest(c, "projects", defaults);
+  if (window.kind === "rejected") return window.response;
+  const { from, to } = window;
   const projects = getSnapshotAggregation(
     scanSource,
     scanResult.sessions,
     ["projects", from, to],
     () => {
-      const sessions = filterSessionsByActivityWindow(scanResult.sessions, from, to);
+      const tree = buildSessionTree(scanResult.sessions);
+      const sessions = filterSessionTreeByActivityWindow(scanResult.sessions, from, to, tree);
       return {
-        projects: attachProjectMetrics(listCachedProjectGroups(sessions), sessions)
+        projects: attachProjectMetricsFromTree(listCachedProjectGroups(sessions), tree, from, to)
       };
     }
   );
@@ -495,7 +620,13 @@ function handleGetProjects(c, scanSource, defaults = {}) {
 }
 function handleGetSessions(c, scanSource, defaults = {}) {
   const scanResult = scanSource.getSnapshot();
-  const agent = c.req.query("agent");
+  const params = searchParams(c);
+  const paginationRequested = params.has("limit") || params.has("cursor");
+  const sessionQuery = parseSessionQuery(params, KNOWN_AGENT_NAMES, SESSION_PAGE_LIMIT_POLICY);
+  if (sessionQuery.limit.kind === "invalid") {
+    reportInvalidQueryParameter("sessions", "limit", "rejected");
+    return c.json({ error: sessionQuery.limit.error }, 400);
+  }
   const q = c.req.query("q")?.toLowerCase();
   const cwd = c.req.query("cwd");
   const projectIdentity = parseProjectIdentityFilter(
@@ -506,26 +637,31 @@ function handleGetSessions(c, scanSource, defaults = {}) {
     return c.json({ error: "projectKind and projectKey must form a valid project identity" }, 400);
   }
   const tag = c.req.query("tag")?.toLowerCase();
-  const from = parseDateParam(c.req.query("from"), defaults.from);
-  const to = parseDateParam(c.req.query("to"), defaults.to);
-  let sessions = [];
-  if (agent && scanResult.byAgent[agent]) {
-    sessions = [...scanResult.byAgent[agent]];
-  } else {
-    sessions = [...scanResult.sessions];
-  }
-  if (projectIdentity) {
-    sessions = sessions.filter(
-      (session) => matchesProjectIdentity(session.project_identity, projectIdentity)
-    );
-  } else if (cwd) {
-    const projectScope = createProjectScopeMatcher(cwd);
-    sessions = sessions.filter((s) => matchesProjectScope(s, projectScope));
-  }
-  sessions = filterSessionsByActivityWindow(sessions, from, to);
-  if (tag) {
-    sessions = sessions.filter((s) => s.smart_tags?.includes(tag));
-  }
+  const window = parseDateWindowRequest(c, "sessions", defaults);
+  if (window.kind === "rejected") return window.response;
+  const { from, to } = window;
+  if (sessionQuery.agent.kind === "unknown") {
+    reportInvalidQueryParameter("sessions", "agent", "empty_result");
+  }
+  const agentFilter = sessionQuery.agent.kind === "known" ? sessionQuery.agent.agentName : sessionQuery.agent.kind;
+  let sessions = getSnapshotAggregation(
+    scanSource,
+    scanResult.sessions,
+    ["sessions", agentFilter, projectIdentity?.kind, projectIdentity?.key, cwd, tag, from, to],
+    () => {
+      let filtered = sessionQuery.agent.kind === "all" ? scanResult.sessions : sessionQuery.agent.kind === "known" ? scanResult.byAgent[sessionQuery.agent.agentName] ?? [] : [];
+      if (projectIdentity) {
+        filtered = filtered.filter(
+          (session) => matchesProjectIdentity(session.project_identity, projectIdentity)
+        );
+      } else if (cwd) {
+        const projectScope = createProjectScopeMatcher(cwd);
+        filtered = filtered.filter((session) => matchesProjectScope(session, projectScope));
+      }
+      filtered = filterSessionsByActivityWindow(filtered, from, to);
+      return tag ? filtered.filter((session) => session.smart_tags?.includes(tag)) : filtered;
+    }
+  );
   const aliases = loadAliasView();
   if (q) {
     sessions = sessions.filter((session) => {
@@ -533,15 +669,93 @@ function handleGetSessions(c, scanSource, defaults = {}) {
       return session.title.toLowerCase().includes(q) || alias?.toLowerCase().includes(q);
     });
   }
+  if (paginationRequested) {
+    const page = paginateSessionSnapshot(sessions, {
+      cursor: params.get("cursor") ?? void 0,
+      limit: sessionQuery.limit.value,
+      query: params,
+      snapshotIdentity: scanResult.sessions,
+      viewIdentity: aliases
+    });
+    if (page.kind === "invalid_cursor") {
+      reportInvalidQueryParameter("sessions", "cursor", "rejected");
+      return c.json({ error: "cursor is invalid for this request" }, 400);
+    }
+    if (page.kind === "stale_snapshot") {
+      return c.json({ error: "session snapshot changed; restart pagination" }, 409);
+    }
+    return c.json({
+      sessions: page.items.map(
+        (session) => toSessionListItem(aliases.decorate(session, getSessionHeadReference(session)))
+      ),
+      ...page.nextCursor ? { nextCursor: page.nextCursor } : {}
+    });
+  }
   return c.json({
     sessions: sessions.map(
       (session) => toSessionListItem(aliases.decorate(session, getSessionHeadReference(session)))
     )
   });
 }
+function withParentContext(results, sessions, aliases) {
+  if (!results.some((result) => result.session.parent_reference)) return results;
+  const byRouteKey = new Map(
+    sessions.map((session) => [
+      getSessionRouteKey(getSessionAgentKey(session), session.id),
+      session
+    ])
+  );
+  return results.map((result) => {
+    const parentReference = result.session.parent_reference;
+    if (!parentReference) return result;
+    const parent = byRouteKey.get(formatSessionReference(parentReference));
+    if (!parent) return result;
+    const reference = normalizeSessionReference(parentReference);
+    return { ...result, parent: { reference, title: aliases.get(reference) ?? parent.title } };
+  });
+}
+var ALIAS_SEARCH_RESULT_SHARE = 0.25;
+function searchResultKey(result) {
+  return `${result.reference.agentName}\0${result.reference.sessionId}`;
+}
+function uniqueSearchResults(results) {
+  const seen = /* @__PURE__ */ new Set();
+  return results.filter((result) => {
+    const key = searchResultKey(result);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function mergeAliasSearchResults(rankedResults, aliasResults, limit) {
+  if (limit <= 0) return [];
+  const ranked = uniqueSearchResults(rankedResults);
+  const rankedKeys = new Set(ranked.map(searchResultKey));
+  const aliases = uniqueSearchResults(aliasResults).filter(
+    (result) => !rankedKeys.has(searchResultKey(result))
+  );
+  if (ranked.length === 0) return aliases.slice(0, limit);
+  if (aliases.length === 0) return ranked.slice(0, limit);
+  const aliasQuota = Math.min(
+    limit - 1,
+    Math.max(1, Math.floor(limit * ALIAS_SEARCH_RESULT_SHARE))
+  );
+  const rankedQuota = limit - aliasQuota;
+  return [
+    ...ranked.slice(0, rankedQuota),
+    ...aliases.slice(0, aliasQuota),
+    ...ranked.slice(rankedQuota),
+    ...aliases.slice(aliasQuota)
+  ].slice(0, limit);
+}
 function handleSearchSessions(c, scanSource, defaults = {}) {
   const query = c.req.query("q")?.trim() ?? "";
   const scanResult = scanSource.getSnapshot();
+  const sessionQuery = parseSessionQuery(searchParams(c), KNOWN_AGENT_NAMES, SEARCH_LIMIT_POLICY);
+  if (sessionQuery.limit.kind === "invalid") {
+    reportInvalidQueryParameter("search", "limit", "rejected");
+    return c.json({ error: sessionQuery.limit.error }, 400);
+  }
   const projectIdentity = parseProjectIdentityFilter(
     c.req.query("projectKind"),
     c.req.query("projectKey")
@@ -549,22 +763,42 @@ function handleSearchSessions(c, scanSource, defaults = {}) {
   if (projectIdentity === null) {
     return c.json({ error: "projectKind and projectKey must form a valid project identity" }, 400);
   }
-  const searchOptions = parseSearchOptions(c, defaults, projectIdentity);
+  const window = parseDateWindowRequest(c, "search", defaults);
+  if (window.kind === "rejected") return window.response;
+  if (sessionQuery.agent.kind === "unknown") {
+    reportInvalidQueryParameter("search", "agent", "empty_result");
+    return c.json({ results: [] });
+  }
+  const searchOptions = parseSearchOptions(
+    c,
+    window,
+    {
+      agent: sessionQuery.agent.kind === "known" ? sessionQuery.agent.agentName : void 0,
+      limit: sessionQuery.limit.value
+    },
+    projectIdentity
+  );
   const aliases = loadAliasView();
   const results = executeSessionSearch(query, searchOptions, scanResult).map((result) => ({
     ...result,
     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.reference.agentName}\0${result.reference.sessionId}`, result);
-  }
-  return c.json({ results: [...deduped.values()].slice(0, searchOptions.limit ?? 50) });
+  const mergedResults = mergeAliasSearchResults(results, aliasResults, searchOptions.limit ?? 50);
+  return c.json({
+    results: withParentContext(mergedResults, scanResult.sessions, aliases)
+  });
 }
 function handleGetFileActivity(c, defaults = {}) {
-  const limitValue = Number(c.req.query("limit"));
-  const limit = Number.isFinite(limitValue) && limitValue > 0 ? Math.min(limitValue, 200) : 50;
+  const sessionQuery = parseSessionQuery(
+    searchParams(c),
+    KNOWN_AGENT_NAMES,
+    FILE_ACTIVITY_LIMIT_POLICY
+  );
+  if (sessionQuery.limit.kind === "invalid") {
+    reportInvalidQueryParameter("file-activity", "limit", "rejected");
+    return c.json({ error: sessionQuery.limit.error }, 400);
+  }
   const projectIdentity = parseProjectIdentityFilter(
     c.req.query("projectKind"),
     c.req.query("projectKey")
@@ -572,10 +806,16 @@ function handleGetFileActivity(c, defaults = {}) {
   if (projectIdentity === null) {
     return c.json({ error: "projectKind and projectKey must form a valid project identity" }, 400);
   }
+  const window = parseDateWindowRequest(c, "file-activity", defaults);
+  if (window.kind === "rejected") return window.response;
+  if (sessionQuery.agent.kind === "unknown") {
+    reportInvalidQueryParameter("file-activity", "agent", "empty_result");
+    return c.json({ activity: [] });
+  }
   const aliases = loadAliasView();
   return c.json({
     activity: listFileActivity({
-      agent: optionalQueryValue(c.req.query("agent")),
+      agent: sessionQuery.agent.kind === "known" ? sessionQuery.agent.agentName : void 0,
       sessionId: optionalQueryValue(c.req.query("sessionId")),
       projectKind: projectIdentity?.kind,
       projectKey: projectIdentity?.key,
@@ -583,9 +823,9 @@ function handleGetFileActivity(c, defaults = {}) {
       cwd: optionalQueryValue(c.req.query("cwd")),
       path: optionalQueryValue(c.req.query("path")),
       kind: parseFileActivityKind(optionalQueryValue(c.req.query("kind"))),
-      from: parseDateParam(c.req.query("from"), defaults.from),
-      to: parseDateParam(c.req.query("to"), defaults.to),
-      limit
+      from: window.from,
+      to: window.to,
+      limit: sessionQuery.limit.value
     }).map((activity) => decorateFileActivity(activity, aliases))
   });
 }
@@ -600,10 +840,12 @@ async function handleGetSessionData(c, scanSource) {
     return c.json({ error: "Missing session ID" }, 400);
   }
   try {
-    const result = materializeSessionDetailResponse(scanSource.getSnapshot(), {
+    const reference = {
       agentName,
       sessionId
-    });
+    };
+    const messageCursor = optionalQueryValue(c.req.query("messageCursor"));
+    const result = messageCursor ? materializeSessionDetailResponse(scanSource.getSnapshot(), reference, { messageCursor }) : materializeSessionDetailResponse(scanSource.getSnapshot(), reference);
     if (result.status === "unknown-agent") {
       return c.json({ error: `Unknown agent: ${agentName}` }, 404);
     }
@@ -619,6 +861,8 @@ async function handleGetSessionData(c, scanSource) {
       agent: agentName,
       session_id: sessionId,
       messages: result.status === "found-json" ? result.messageCount : result.data.messages.length,
+      sent_messages: result.status === "found-json" ? result.sentMessageCount : result.data.messages.length,
+      message_update: result.data.message_update ?? "reset",
       duration_ms: Math.round(performance.now() - startedAt)
     });
     const aliases = loadAliasView();
@@ -637,7 +881,7 @@ async function handleGetSessionData(c, scanSource) {
       duration_ms: Math.round(performance.now() - startedAt),
       error: message
     });
-    return c.json({ error: message }, 500);
+    return c.json({ error: "Failed to load session" }, 500);
   }
 }
 async function handlePostClientLog(c) {
@@ -650,12 +894,27 @@ async function handlePostClientLog(c) {
   appLogger.info(`client.${event}`, sanitizeClientLogData(payload?.data));
   return c.json({ ok: true });
 }
-function handleGetBookmarks(c) {
+function materializeStoredBookmarks(scanSource, bookmarks, aliases) {
+  const snapshot = scanSource.getSnapshot();
+  const sessionIndex = getSnapshotAggregation(
+    scanSource,
+    snapshot.sessions,
+    ["bookmark-session-index"],
+    () => createSessionIndex(snapshot.sessions)
+  );
+  return materializeBookmarkViews(bookmarks, {
+    liveSessionsByReference: sessionIndex.byRouteKey,
+    knownAgentNames: KNOWN_AGENT_NAME_SET,
+    resolveCachedSessions: loadCachedSessionHeads
+  }).map((bookmark) => decorateBookmark(bookmark, aliases));
+}
+function handleGetBookmarks(c, scanSource) {
   return withStorageErrors(
     () => {
       const aliases = loadAliasView();
+      const bookmarks = materializeStoredBookmarks(scanSource, listBookmarks(), aliases);
       return c.json({
-        bookmarks: listBookmarks().map((bookmark) => decorateBookmark(bookmark, aliases)),
+        bookmarks,
         storageAvailable: true
       });
     },
@@ -663,7 +922,7 @@ function handleGetBookmarks(c) {
   );
 }
 async function handlePutBookmark(c) {
-  const payload = parseBookmarkPayload(await c.req.json().catch(() => null));
+  const payload = parseBookmarkReference(await c.req.json().catch(() => null));
   if (!payload) {
     return c.json({ error: "Invalid bookmark payload" }, 400);
   }
@@ -672,17 +931,21 @@ async function handlePutBookmark(c) {
     () => c.json({ error: "Bookmark storage is unavailable" }, 503)
   );
 }
-async function handleImportBookmarks(c) {
+async function handleImportBookmarks(c, scanSource) {
   const payload = await c.req.json().catch(() => null);
   if (!Array.isArray(payload)) {
     return c.json({ error: "Invalid bookmark payload" }, 400);
   }
-  const bookmarks = payload.map((entry) => parseBookmarkPayload(entry)).filter((entry) => entry !== null);
+  const bookmarks = payload.map((entry) => parseBookmarkImport(entry)).filter((entry) => entry !== null);
   if (bookmarks.length !== payload.length) {
     return c.json({ error: "Invalid bookmark payload" }, 400);
   }
   return withStorageErrors(
-    () => c.json({ bookmarks: importBookmarks(bookmarks), storageAvailable: true }),
+    () => {
+      const imported = importBookmarks(bookmarks);
+      const views = materializeStoredBookmarks(scanSource, imported, loadAliasView());
+      return c.json({ bookmarks: views, storageAvailable: true });
+    },
     () => c.json({ error: "Bookmark storage is unavailable" }, 503)
   );
 }
@@ -748,6 +1011,8 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
   if (projectIdentity === null) {
     return c.json({ error: "projectKind and projectKey must form a valid project identity" }, 400);
   }
+  const dateWindow = parseDateWindowRequest(c, "dashboard", defaults);
+  if (dateWindow.kind === "rejected") return dateWindow.response;
   const { from, to, days } = resolveTimeWindow({
     mode: "dashboard",
     query: {
@@ -762,7 +1027,8 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
     projectKind: projectIdentity?.kind,
     projectKey: projectIdentity?.key
   };
-  const fixedTo = parseDateParam(c.req.query("to"), defaults.to);
+  const compare = from == null ? void 0 : { from: addCalendarDays(from, -(days ?? countCalendarDays(from, to))), to: from - 1 };
+  const fixedTo = dateWindow.to;
   const aggregate = getSnapshotAggregation(
     scanSource,
     scanResult.sessions,
@@ -772,7 +1038,9 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
       scope.projectKind,
       scope.projectKey,
       from,
-      fixedTo ?? startOfCalendarDay(to)
+      fixedTo ?? startOfCalendarDay(to),
+      compare?.from,
+      compare?.to
     ],
     () => {
       const agentInfo = getAgentInfoMap({});
@@ -782,7 +1050,8 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
         scope,
         from,
         to,
-        agentInfoMap
+        agentInfoMap,
+        compare
       });
     }
   );
@@ -796,7 +1065,14 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
       to,
       limit: 12
     }),
-    window: { from, to, days }
+    modelCost: listModelCostDistribution({
+      agent: scope.agent,
+      projectKind: scope.projectKind,
+      projectKey: scope.projectKey,
+      from,
+      to
+    }),
+    window: { from, to, days, compareFrom: compare?.from, compareTo: compare?.to }
   };
   const aliases = loadAliasView();
   return c.json({
@@ -811,52 +1087,174 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
   });
 }
 
+// src/api/sse-event-buffer.ts
+var MAX_PENDING_CRITICAL_SSE_FRAMES = 64;
+function scanStatusMilestone(status) {
+  const agentStates = Object.entries(status.agentStatuses).sort(([left], [right]) => left.localeCompare(right)).map(([agentName, agentStatus]) => [agentName, agentStatus.status, agentStatus.error ?? null]);
+  return JSON.stringify([
+    status.active,
+    status.phase,
+    status.totalAgents,
+    status.pendingAgents,
+    status.scanningAgents,
+    status.completedAgents,
+    agentStates,
+    status.backfill.active,
+    status.backfill.currentAgent ?? null,
+    status.backfill.pendingAgents,
+    status.backfill.completedAgents,
+    status.backfill.failedAgents,
+    status.backfill.progress?.phase ?? null,
+    status.searchIndexMaintenance?.active ?? false,
+    status.searchIndexMaintenance?.currentAgent ?? null,
+    status.searchIndexMaintenance?.pendingAgents ?? [],
+    status.searchIndexMaintenance?.completedAgents ?? [],
+    status.searchIndexMaintenance?.failedAgents ?? []
+  ]);
+}
+var SseEventBuffer = class {
+  constructor(controller, onOverflow) {
+    this.controller = controller;
+    this.onOverflow = onOverflow;
+  }
+  controller;
+  onOverflow;
+  encoder = new TextEncoder();
+  frames = [];
+  replaceableStatus = null;
+  lastStatusMilestone = null;
+  criticalFrameCount = 0;
+  isClosed = false;
+  enqueue(event, data) {
+    if (!this.freezeReplaceableStatus()) return;
+    this.appendCritical(this.frame(event, data));
+  }
+  enqueueScanStatus(status) {
+    if (this.isClosed) return;
+    const milestone = scanStatusMilestone(status);
+    const bytes = this.frame(status.type, status);
+    if (this.lastStatusMilestone !== milestone) {
+      if (!this.freezeReplaceableStatus()) return;
+      this.lastStatusMilestone = milestone;
+      this.appendCritical(bytes);
+      return;
+    }
+    if (this.replaceableStatus) {
+      this.replaceableStatus.bytes = bytes;
+      return;
+    }
+    const frame = { bytes, critical: false };
+    this.frames.push(frame);
+    this.replaceableStatus = frame;
+    this.drain();
+  }
+  enqueueHeartbeat() {
+    if (this.isClosed || this.frames.length > 0 || this.controller.desiredSize == null || this.controller.desiredSize <= 0) {
+      return;
+    }
+    this.controller.enqueue(this.encoder.encode(": keepalive\n\n"));
+  }
+  drain() {
+    while (!this.isClosed && this.frames.length > 0 && this.controller.desiredSize != null && this.controller.desiredSize > 0) {
+      const frame = this.frames.shift();
+      if (frame === this.replaceableStatus) this.replaceableStatus = null;
+      if (frame.critical) this.criticalFrameCount -= 1;
+      this.controller.enqueue(frame.bytes);
+    }
+  }
+  close() {
+    this.isClosed = true;
+    this.frames.length = 0;
+    this.replaceableStatus = null;
+    this.criticalFrameCount = 0;
+  }
+  freezeReplaceableStatus() {
+    if (!this.replaceableStatus) return !this.isClosed;
+    if (this.criticalFrameCount >= MAX_PENDING_CRITICAL_SSE_FRAMES) {
+      this.overflow();
+      return false;
+    }
+    this.replaceableStatus.critical = true;
+    this.replaceableStatus = null;
+    this.criticalFrameCount += 1;
+    return true;
+  }
+  appendCritical(bytes) {
+    if (this.isClosed) return;
+    if (this.criticalFrameCount >= MAX_PENDING_CRITICAL_SSE_FRAMES) {
+      this.overflow();
+      return;
+    }
+    this.frames.push({ bytes, critical: true });
+    this.criticalFrameCount += 1;
+    this.drain();
+  }
+  overflow() {
+    if (this.isClosed) return;
+    this.close();
+    this.onOverflow();
+  }
+  frame(event, data) {
+    return this.encoder.encode(`event: ${event}
+data: ${JSON.stringify(data)}
+
+`);
+  }
+};
+
 // src/api/routes.ts
 function createSseResponse(eventSource, signal) {
-  const encoder = new TextEncoder();
   let cancelStream = () => {
   };
+  let drainStream = () => {
+  };
   return new Response(
     new ReadableStream({
       start(controller) {
         let isClosed = false;
-        const write = (event, data) => {
-          if (isClosed) return;
-          controller.enqueue(encoder.encode(`event: ${event}
-`));
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}
-
-`));
+        let unsubscribeSessions = () => {
         };
-        write("connected", { timestamp: Date.now() });
-        write("scan-status", eventSource.getScanStatus());
-        const unsubscribeSessions = eventSource.subscribe((event) => {
-          write(event.type, event);
-        });
-        const unsubscribeScanStatus = eventSource.subscribeScanStatus((event) => {
-          write(event.type, event);
-        });
-        const heartbeat = setInterval(() => {
-          if (!isClosed) controller.enqueue(encoder.encode(": keepalive\n\n"));
-        }, 15e3);
+        let unsubscribeScanStatus = () => {
+        };
+        let abortStream = () => {
+        };
+        let heartbeat;
+        let buffer;
         const cleanup = () => {
           if (isClosed) return false;
           isClosed = true;
-          clearInterval(heartbeat);
+          buffer.close();
+          if (heartbeat) clearInterval(heartbeat);
           unsubscribeSessions();
           unsubscribeScanStatus();
           signal.removeEventListener("abort", abortStream);
           return true;
         };
-        const abortStream = () => {
+        abortStream = () => {
           if (cleanup()) controller.close();
         };
+        buffer = new SseEventBuffer(controller, () => {
+          if (cleanup()) controller.error(new Error("SSE client fell behind"));
+        });
+        drainStream = () => buffer.drain();
+        buffer.enqueue("connected", { timestamp: Date.now() });
+        buffer.enqueueScanStatus(eventSource.getScanStatus());
+        unsubscribeSessions = eventSource.subscribe((event) => {
+          buffer.enqueue(event.type, event);
+        });
+        unsubscribeScanStatus = eventSource.subscribeScanStatus((event) => {
+          buffer.enqueueScanStatus(event);
+        });
+        heartbeat = setInterval(() => buffer.enqueueHeartbeat(), 15e3);
         cancelStream = () => {
           cleanup();
         };
         if (signal.aborted) abortStream();
         else signal.addEventListener("abort", abortStream, { once: true });
       },
+      pull() {
+        drainStream();
+      },
       cancel() {
         cancelStream();
       }
@@ -888,23 +1286,140 @@ function createApiRoutes(scanSource, eventSource, options = {}) {
   api.get("/file-activity", (c) => handleGetFileActivity(c, listDefaults));
   api.get("/sessions/:agent/:id", (c) => handleGetSessionData(c, scanSource));
   api.get("/dashboard", (c) => handleGetDashboard(c, scanSource, listDefaults));
-  api.get("/bookmarks", (c) => handleGetBookmarks(c));
+  api.get("/bookmarks", (c) => handleGetBookmarks(c, scanSource));
   api.put("/bookmarks", (c) => handlePutBookmark(c));
-  api.post("/bookmarks/import", (c) => handleImportBookmarks(c));
+  api.post("/bookmarks/import", (c) => handleImportBookmarks(c, scanSource));
   api.delete("/bookmarks/:agent/:id", (c) => handleDeleteBookmark(c));
   api.put("/session-aliases/:agent/:id", (c) => handlePutSessionAlias(c));
   api.delete("/session-aliases/:agent/:id", (c) => handleDeleteSessionAlias(c));
   api.post("/logs", (c) => handlePostClientLog(c));
   if (eventSource) {
-    api.get("/events", (c) => createSseResponse(eventSource, c.req.raw.signal));
+    api.get("/events", (c) => {
+      const signal = options.shutdownSignal ? AbortSignal.any([c.req.raw.signal, options.shutdownSignal]) : c.req.raw.signal;
+      return createSseResponse(eventSource, signal);
+    });
   }
   return api;
 }
 
+// src/loopback-authority.ts
+import { isIP } from "net";
+var LOOPBACK_AUTHORITY_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+function canonicalizeHostname(hostname) {
+  const unwrapped = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+  const authorityHost = isIP(unwrapped) === 6 ? `[${unwrapped}]` : unwrapped;
+  try {
+    return new URL(`http://${authorityHost}`).hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+  } catch {
+    return null;
+  }
+}
+function parseAuthority(value) {
+  if (!value || value !== value.trim()) return null;
+  const bracketed = /^\[([^\]]+)\]:(\d{1,5})$/.exec(value);
+  const plain = /^([^:[\]]+):(\d{1,5})$/.exec(value);
+  const match = bracketed ?? plain;
+  if (!match) return null;
+  const port = Number(match[2]);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+  const rawHostname = match[1];
+  const authorityHost = bracketed ? `[${rawHostname}]` : rawHostname;
+  try {
+    const parsed = new URL(`http://${authorityHost}:${port}`);
+    if (parsed.username || parsed.password) return null;
+    const hostname = parsed.hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+    return {
+      hostname,
+      port,
+      normalized: isIP(hostname) === 6 ? `[${hostname}]:${port}` : `${hostname}:${port}`
+    };
+  } catch {
+    return null;
+  }
+}
+function hostHeaders(rawHeaders) {
+  const values = [];
+  for (let index = 0; index < rawHeaders.length; index += 2) {
+    if (rawHeaders[index]?.toLowerCase() === "host") values.push(rawHeaders[index + 1] ?? "");
+  }
+  return values;
+}
+function validateLoopbackAuthority(rawHeaders, listenerHostname, listenerPort) {
+  if (listenerPort === null) return { allowed: false, reason: "listener-not-ready" };
+  const hosts = hostHeaders(rawHeaders);
+  if (hosts.length === 0) return { allowed: false, reason: "missing-host" };
+  if (hosts.length !== 1) return { allowed: false, reason: "multiple-hosts" };
+  const authority = parseAuthority(hosts[0]);
+  if (!authority) return { allowed: false, reason: "invalid-host" };
+  if (authority.port !== listenerPort) {
+    return { allowed: false, reason: "port-mismatch", authority: authority.normalized };
+  }
+  const listener = canonicalizeHostname(listenerHostname);
+  if (!LOOPBACK_AUTHORITY_HOSTS.has(authority.hostname) && authority.hostname !== listener) {
+    return {
+      allowed: false,
+      reason: "hostname-not-allowed",
+      authority: authority.normalized
+    };
+  }
+  return { allowed: true, authority: authority.normalized };
+}
+
+// src/loopback-write-guard.ts
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var JSON_BODY_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH"]);
+var ALLOWED_FETCH_SITES = /* @__PURE__ */ new Set(["same-origin", "none"]);
+function mediaType(contentType) {
+  return contentType?.split(";", 1)[0]?.trim().toLowerCase() || null;
+}
+function isSameOrigin(origin, requestOrigin) {
+  try {
+    return new URL(origin).origin === requestOrigin;
+  } catch {
+    return false;
+  }
+}
+function evaluateLoopbackWriteRequest(request) {
+  const method = request.method.toUpperCase();
+  if (SAFE_METHODS.has(method)) return { allowed: true };
+  if (JSON_BODY_METHODS.has(method) && mediaType(request.contentType) !== "application/json") {
+    return { allowed: false, reason: "content-type", status: 415 };
+  }
+  if (request.fetchSite && !ALLOWED_FETCH_SITES.has(request.fetchSite)) {
+    return { allowed: false, reason: "fetch-site", status: 403 };
+  }
+  if (request.origin && !isSameOrigin(request.origin, request.requestOrigin)) {
+    return { allowed: false, reason: "origin", status: 403 };
+  }
+  return { allowed: true };
+}
+function loopbackWriteGuard() {
+  return async (c, next) => {
+    const url = new URL(c.req.url);
+    const decision = evaluateLoopbackWriteRequest({
+      method: c.req.method,
+      contentType: c.req.header("Content-Type"),
+      fetchSite: c.req.header("Sec-Fetch-Site"),
+      origin: c.req.header("Origin"),
+      requestOrigin: url.origin
+    });
+    if (!decision.allowed) {
+      appLogger.warn("http.loopback_write.rejected", {
+        method: c.req.method,
+        path: url.pathname,
+        reason: decision.reason
+      });
+      const error = decision.reason === "content-type" ? "Write requests require application/json" : "Cross-origin write request rejected";
+      return c.json({ error }, decision.status);
+    }
+    await next();
+  };
+}
+
 // src/remote-access.ts
 import { randomBytes, timingSafeEqual } from "crypto";
 import { readFileSync } from "fs";
-import { isIP } from "net";
+import { isIP as isIP2 } from "net";
 var REMOTE_ACCESS_QUERY_PARAM = "access_token";
 var RemoteTransportError = class extends Error {
 };
@@ -935,6 +1450,13 @@ function resolveRemoteTransport(request) {
   if (request.trustProxy) return { kind: "trusted-proxy" };
   return isLoopbackHostname(request.hostname) ? { kind: "loopback" } : { kind: "plaintext" };
 }
+function resolveRemoteAccessPolicy(hostname, transport) {
+  const bindCategory = isLoopbackHostname(hostname) ? "loopback" : "network";
+  return {
+    bindCategory,
+    authenticationRequired: bindCategory === "network" || transport.kind !== "loopback"
+  };
+}
 var FORWARDED_PROTO_HEADER = "X-Forwarded-Proto";
 function requireProxyTls() {
   return async (c, next) => {
@@ -951,7 +1473,7 @@ function createRemoteAccessToken() {
 function isLoopbackHostname(hostname) {
   const normalized = hostname.toLowerCase().replace(/^\[(.*)\]$/, "$1");
   if (normalized === "localhost" || normalized === "::1") return true;
-  return isIP(normalized) === 4 && normalized.startsWith("127.");
+  return isIP2(normalized) === 4 && normalized.startsWith("127.");
 }
 function tokenMatches(actual, expected) {
   if (!actual) return false;
@@ -981,6 +1503,7 @@ function remoteAccessAuth(expectedToken) {
 
 // src/server.ts
 var MAX_API_REQUEST_BYTES = 1024 * 1024;
+var SERVER_CLOSE_GRACE_MS = 1e3;
 function findWebDistPath() {
   const __dirname2 = dirname(fileURLToPath(import.meta.url));
   const packagedPath = resolve(__dirname2, "web");
@@ -1020,17 +1543,91 @@ function getListeningPort(server, fallback) {
   const address = server.address();
   return typeof address === "object" && address !== null ? address.port : fallback;
 }
+async function closeHttpServer(server, port) {
+  if (!server) return;
+  let forceCloseTimer;
+  const gracefulClose = new Promise((resolve4) => server.close(() => resolve4()));
+  const forceClose = new Promise((resolve4) => {
+    forceCloseTimer = setTimeout(() => {
+      appLogger.warn("server.shutdown.force_close", {
+        port,
+        grace_ms: SERVER_CLOSE_GRACE_MS
+      });
+      if ("closeAllConnections" in server) server.closeAllConnections();
+      resolve4();
+    }, SERVER_CLOSE_GRACE_MS);
+    forceCloseTimer.unref();
+  });
+  try {
+    await Promise.race([gracefulClose, forceClose]);
+  } finally {
+    if (forceCloseTimer) clearTimeout(forceCloseTimer);
+  }
+}
 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) {
+  const transport = options.transport ?? resolveRemoteTransport({ hostname });
+  const accessPolicy = resolveRemoteAccessPolicy(hostname, transport);
+  const remoteAccessToken = accessPolicy.authenticationRequired ? options.remoteAccessToken ?? (options.remoteAccess ? createRemoteAccessToken() : null) : null;
+  const loopbackAuthorityEnabled = !accessPolicy.authenticationRequired;
+  const shutdownController = new AbortController();
+  let actualPort = null;
+  appLogger.info("server.access_policy", {
+    bind_category: accessPolicy.bindCategory,
+    transport: transport.kind,
+    authentication: remoteAccessToken ? "token" : "none",
+    loopback_authority: loopbackAuthorityEnabled ? "enabled" : "disabled"
+  });
+  if (accessPolicy.authenticationRequired && !remoteAccessToken) {
     throw new Error(
       `Refusing to expose CodeSesh on ${hostname} without authentication. Add --remote-access to continue.`
     );
   }
+  app.use(
+    "*",
+    secureHeaders({
+      contentSecurityPolicy: {
+        defaultSrc: ["'self'"],
+        baseUri: ["'none'"],
+        connectSrc: ["'self'"],
+        fontSrc: ["'self'", "data:"],
+        formAction: ["'self'"],
+        frameAncestors: ["'none'"],
+        imgSrc: ["'self'", "data:"],
+        objectSrc: ["'none'"],
+        scriptSrc: ["'self'"],
+        scriptSrcAttr: ["'none'"],
+        styleSrc: ["'self'", "'unsafe-inline'"]
+      },
+      crossOriginOpenerPolicy: false,
+      crossOriginResourcePolicy: false,
+      originAgentCluster: false,
+      referrerPolicy: "no-referrer",
+      strictTransportSecurity: false,
+      xContentTypeOptions: "nosniff",
+      xDnsPrefetchControl: false,
+      xDownloadOptions: false,
+      xFrameOptions: "DENY",
+      xPermittedCrossDomainPolicies: false,
+      xXssProtection: false
+    })
+  );
+  if (loopbackAuthorityEnabled) {
+    app.use("*", async (c, next) => {
+      const decision = validateLoopbackAuthority(c.env.incoming.rawHeaders, hostname, actualPort);
+      if (!decision.allowed) {
+        appLogger.warn("http.loopback_authority.rejected", {
+          method: c.req.method,
+          path: new URL(c.req.url).pathname,
+          reason: decision.reason,
+          authority: decision.authority
+        });
+        return c.json({ error: "Loopback request authority rejected" }, 403);
+      }
+      await next();
+    });
+  }
   app.use("*", async (c, next) => {
     const startedAt = performance.now();
     let thrown;
@@ -1057,6 +1654,7 @@ async function createServer(port, store, options = {}) {
   if (remoteAccessToken) {
     app.use("/api/*", remoteAccessAuth(remoteAccessToken));
   }
+  app.use("/api/*", loopbackWriteGuard());
   app.use(
     "/api/*",
     bodyLimit({
@@ -1068,7 +1666,8 @@ async function createServer(port, store, options = {}) {
   const routeOptions = {
     defaultSessionFrom: options.defaultSessionFrom,
     defaultSessionTo: options.defaultSessionTo,
-    defaultSessionDays: options.defaultSessionDays
+    defaultSessionDays: options.defaultSessionDays,
+    shutdownSignal: shutdownController.signal
   };
   app.route("/api", createApiRoutes(store, store, routeOptions));
   const webDistPath = options.webDistPath ?? findWebDistPath();
@@ -1078,7 +1677,6 @@ async function createServer(port, store, options = {}) {
   }
   const attempts = Math.max(1, options.portFallbackAttempts ?? 1);
   let server = null;
-  let actualPort = port;
   for (let offset = 0; offset < attempts; offset += 1) {
     const candidatePort = port + offset;
     server = serve({
@@ -1110,7 +1708,7 @@ async function createServer(port, store, options = {}) {
     }
   }
   const scheme = transport.kind === "tls" ? "https" : "http";
-  const baseUrl = isLoopback ? `${scheme}://localhost:${actualPort}` : `${scheme}://${hostname}:${actualPort}`;
+  const baseUrl = accessPolicy.bindCategory === "loopback" ? `${scheme}://localhost:${actualPort}` : `${scheme}://${hostname}:${actualPort}`;
   const url = remoteAccessToken ? `${baseUrl}/?${REMOTE_ACCESS_QUERY_PARAM}=${encodeURIComponent(remoteAccessToken)}` : baseUrl;
   appLogger.info("server.listen", {
     port: actualPort,
@@ -1119,7 +1717,7 @@ async function createServer(port, store, options = {}) {
     remote_access: Boolean(remoteAccessToken),
     transport: transport.kind
   });
-  if (!isLoopback) {
+  if (accessPolicy.authenticationRequired) {
     appLogger.warn("server.listen.remote_access", {
       hostname,
       port: actualPort,
@@ -1133,6 +1731,14 @@ async function createServer(port, store, options = {}) {
       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
+`
+      );
+    }
+    if (transport.kind === "trusted-proxy") {
+      appLogger.warn("server.listen.proxy_logging", { hostname, port: actualPort });
+      console.warn(
+        `\u26A0 URL \u4E2D\u7684\u8BBF\u95EE\u4EE4\u724C\u4F1A\u7528\u4E8E SSE \u91CD\u8FDE\uFF0C\u5E76\u53EF\u80FD\u5199\u5165\u53D7\u4FE1\u53CD\u5411\u4EE3\u7406\u7684\u8BBF\u95EE\u65E5\u5FD7\u3002
+  \u8BF7\u5728\u4EE3\u7406\u914D\u7F6E\u4E2D\u5173\u95ED\u67E5\u8BE2\u53C2\u6570\u65E5\u5FD7\uFF0C\u6216\u5BF9 access_token \u53C2\u6570\u8131\u654F\u3002
 `
       );
     }
@@ -1141,14 +1747,15 @@ async function createServer(port, store, options = {}) {
     url,
     shutdown: async () => {
       appLogger.info("server.shutdown", { port: actualPort });
-      await new Promise((resolve4) => {
-        if (!server) {
-          resolve4();
-          return;
-        }
-        server.close(() => resolve4());
-      });
-      await store.shutdown();
+      shutdownController.abort();
+      try {
+        appLogger.info("server.shutdown.phase", { phase: "http-closing", port: actualPort });
+        await closeHttpServer(server, actualPort);
+      } finally {
+        appLogger.info("server.shutdown.phase", { phase: "store-closing", port: actualPort });
+        await store.shutdown();
+      }
+      appLogger.info("server.shutdown.phase", { phase: "complete", port: actualPort });
     }
   };
 }
@@ -1307,12 +1914,88 @@ var AgentOperationScheduler = class {
   }
 };
 
+// src/backfill-lifecycle.ts
+var BackfillLifecycle = class {
+  attempts = /* @__PURE__ */ new Map();
+  nextAttemptId = 1;
+  enqueue(agentName) {
+    const current = this.attempts.get(agentName);
+    if (current?.status === "queued" || current?.status === "running") return null;
+    const attempt = {
+      agentName,
+      attemptId: this.nextAttemptId++,
+      status: "queued"
+    };
+    this.attempts.set(agentName, attempt);
+    return attempt;
+  }
+  startNext() {
+    if ([...this.attempts.values()].some((attempt) => attempt.status === "running")) return null;
+    const queued = [...this.attempts.values()].filter((attempt) => attempt.status === "queued").sort((left, right) => left.attemptId - right.attemptId)[0];
+    if (!queued) return null;
+    const running = { ...queued, status: "running" };
+    this.attempts.set(running.agentName, running);
+    return running;
+  }
+  updateProgress(attempt, progress) {
+    const current = this.matchingRunningAttempt(attempt);
+    if (!current) return false;
+    this.attempts.set(attempt.agentName, {
+      ...current,
+      progress: { ...current.progress, ...progress }
+    });
+    return true;
+  }
+  complete(attempt, status) {
+    if (!this.matchingRunningAttempt(attempt)) return false;
+    this.attempts.set(attempt.agentName, { ...attempt, status });
+    return true;
+  }
+  cancelAll() {
+    for (const [agentName, attempt] of this.attempts) {
+      if (attempt.status === "queued" || attempt.status === "running") {
+        this.attempts.set(agentName, { ...attempt, status: "cancelled" });
+      }
+    }
+  }
+  runningAttempt() {
+    const running = [...this.attempts.values()].find((attempt) => attempt.status === "running");
+    return running ?? null;
+  }
+  stateFor(agentName) {
+    const state = this.attempts.get(agentName);
+    if (!state) return void 0;
+    return state.status === "running" && state.progress ? { ...state, progress: { ...state.progress } } : { ...state };
+  }
+  status() {
+    const states = [...this.attempts.values()];
+    const queued = states.filter((attempt) => attempt.status === "queued").sort((left, right) => left.attemptId - right.attemptId);
+    const running = states.find((attempt) => attempt.status === "running");
+    const status = {
+      active: running != null || queued.length > 0,
+      pendingAgents: queued.map((attempt) => attempt.agentName),
+      completedAgents: states.filter((attempt) => attempt.status === "committed").map((attempt) => attempt.agentName),
+      failedAgents: states.filter((attempt) => attempt.status === "failed").map((attempt) => attempt.agentName)
+    };
+    if (running) {
+      status.currentAgent = running.agentName;
+      if (running.progress) status.progress = { ...running.progress };
+    }
+    return status;
+  }
+  matchingRunningAttempt(attempt) {
+    const current = this.attempts.get(attempt.agentName);
+    return current?.status === "running" && current.attemptId === attempt.attemptId ? current : null;
+  }
+};
+
 // src/live-session-index.ts
 var LiveSessionIndex = class {
   agents = [];
   agentsByName = /* @__PURE__ */ new Map();
   byAgent = {};
   sessions = [];
+  scanFailures = {};
   signatureCaches = /* @__PURE__ */ new Map();
   initialize(snapshot, options = {}) {
     const agentMap = /* @__PURE__ */ new Map();
@@ -1324,8 +2007,12 @@ var LiveSessionIndex = class {
       (agent) => !options.allowedAgents || options.allowedAgents.has(agent.name.toLowerCase())
     );
     this.agentsByName = new Map(this.agents.map((agent) => [agent.name, agent]));
+    this.scanFailures = { ...snapshot.scanFailures };
     this.byAgent = Object.fromEntries(
-      this.agents.map((agent) => [agent.name, sortSessions(snapshot.byAgent[agent.name] ?? [])])
+      this.agents.flatMap((agent) => {
+        if (this.scanFailures[agent.name] && !(agent.name in snapshot.byAgent)) return [];
+        return [[agent.name, sortSessions(snapshot.byAgent[agent.name] ?? [])]];
+      })
     );
     this.sessions = mergeSortedSessions(Object.values(this.byAgent));
     this.signatureCaches.clear();
@@ -1334,14 +2021,17 @@ var LiveSessionIndex = class {
     return {
       agents: this.agents,
       byAgent: this.byAgent,
-      sessions: this.sessions
+      sessions: this.sessions,
+      ...Object.keys(this.scanFailures).length > 0 ? { scanFailures: this.scanFailures } : {}
     };
   }
   findAgent(agentName) {
     return this.agentsByName.get(agentName);
   }
   commitAgentSessions(agentName, nextSessions, candidateChangedIds = []) {
+    delete this.scanFailures[agentName];
     const previousSessions = this.byAgent[agentName] ?? [];
+    const previousGlobalSessions = this.sessions;
     const signatureCache = this.signatureCache(agentName);
     const { changes, removedSessionIds, counts } = computeSessionDiff(
       previousSessions,
@@ -1354,19 +2044,34 @@ var LiveSessionIndex = class {
     this.byAgent[agentName] = sortSessions(nextSessions);
     this.sessions = mergeSortedSessions(Object.values(this.byAgent));
     if (counts.new === 0 && counts.updated === 0 && counts.removed === 0) return null;
+    const changedSessionHeads = changes.map(({ session }) => ({
+      reference: { agentName, sessionId: session.id },
+      session
+    }));
+    const previousSessionIds = new Set(previousSessions.map((session) => session.id));
+    const newSessionRefs = changedSessionHeads.flatMap(
+      ({ reference }) => previousSessionIds.has(reference.sessionId) ? [] : [reference]
+    );
+    const removedSessionRefs = removedSessionIds.map((sessionId) => ({ agentName, sessionId }));
+    const projectionContext = createSessionProjectionContext(
+      previousGlobalSessions,
+      this.sessions,
+      changedSessionHeads,
+      removedSessionRefs
+    );
     return {
       type: "sessions-updated",
       changedAgents: [agentName],
       newSessions: counts.new,
+      newSessionRefs,
       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 }))
+      changedSessionHeads,
+      projectionRelatedSessionHeads: projectionContext.relatedSessionHeads,
+      projectionSessionOrder: projectionContext.sessionOrder,
+      removedSessionRefs
     };
   }
   signatureCache(agentName) {
@@ -1378,11 +2083,79 @@ var LiveSessionIndex = class {
   }
 };
 
+// src/latest-value-throttle.ts
+var LatestValueThrottle = class {
+  constructor(intervalMs, emit) {
+    this.intervalMs = intervalMs;
+    this.emit = emit;
+  }
+  intervalMs;
+  emit;
+  timer = null;
+  phase = null;
+  pending;
+  hasPending = false;
+  push(value, phase) {
+    if (this.phase !== phase) {
+      this.flush();
+      this.phase = phase;
+      this.emit(value);
+      this.schedule();
+      return;
+    }
+    if (this.timer) {
+      this.pending = value;
+      this.hasPending = true;
+      return;
+    }
+    this.emit(value);
+    this.schedule();
+  }
+  flush() {
+    this.clearTimer();
+    if (!this.hasPending) return;
+    const pending = this.pending;
+    this.pending = void 0;
+    this.hasPending = false;
+    this.emit(pending);
+  }
+  cancel() {
+    this.dropPending();
+    this.phase = null;
+  }
+  schedule() {
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      if (!this.hasPending) return;
+      const pending = this.pending;
+      this.pending = void 0;
+      this.hasPending = false;
+      this.emit(pending);
+      this.schedule();
+    }, this.intervalMs);
+  }
+  clearTimer() {
+    if (!this.timer) return;
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+  dropPending() {
+    this.clearTimer();
+    this.pending = void 0;
+    this.hasPending = false;
+  }
+};
+
 // src/search-index-job-runner.ts
 import { existsSync as existsSync2 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Worker } from "worker_threads";
 
+// src/errors.ts
+function toError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
 // src/pending-search-index-jobs.ts
 var PendingSearchIndexJobBatch = class {
   constructor(id, context, jobs, waiter) {
@@ -1395,6 +2168,7 @@ var PendingSearchIndexJobBatch = class {
   jobsByAgent = /* @__PURE__ */ new Map();
   waiters = [];
   settled = false;
+  started = false;
   get jobs() {
     const jobs = [];
     for (const pending of this.jobsByAgent.values()) {
@@ -1411,6 +2185,17 @@ var PendingSearchIndexJobBatch = class {
     }
     return count;
   }
+  start(onError) {
+    if (this.started) return;
+    this.started = true;
+    for (const waiter of this.waiters) {
+      try {
+        waiter.onStarted?.();
+      } catch (error) {
+        onError(error);
+      }
+    }
+  }
   merge(context, jobs, waiter) {
     this.context = context;
     this.waiters.push(waiter);
@@ -1440,6 +2225,7 @@ var PendingSearchIndexJobBatch = class {
 };
 var PendingSearchIndexJobs = class {
   pendingBatch = null;
+  batches = /* @__PURE__ */ new WeakSet();
   get batchCount() {
     return this.pendingBatch ? 1 : 0;
   }
@@ -1449,14 +2235,15 @@ var PendingSearchIndexJobs = class {
   get changeCount() {
     return this.pendingBatch?.changeCount ?? 0;
   }
-  enqueue(id, context, jobs) {
+  enqueue(id, context, jobs, onStarted) {
     if (jobs.length === 0) return Promise.resolve();
     return new Promise((resolve4, reject) => {
-      const waiter = { resolve: resolve4, reject };
+      const waiter = { resolve: resolve4, reject, onStarted };
       if (this.pendingBatch) {
         this.pendingBatch.merge(context, jobs, waiter);
       } else {
         this.pendingBatch = new PendingSearchIndexJobBatch(id, context, jobs, waiter);
+        this.batches.add(this.pendingBatch);
       }
     });
   }
@@ -1466,7 +2253,9 @@ var PendingSearchIndexJobs = class {
     return batch;
   }
   settle(batch, error) {
-    return batch instanceof PendingSearchIndexJobBatch && batch.settle(error);
+    if (!(batch instanceof PendingSearchIndexJobBatch) || !this.batches.has(batch)) return false;
+    this.batches.delete(batch);
+    return batch.settle(error);
   }
   rejectAll(error) {
     const batch = this.take();
@@ -1475,8 +2264,10 @@ var PendingSearchIndexJobs = class {
 };
 function createPendingChanges(job) {
   return {
+    kind: job.kind,
     context: job.context,
     agentName: job.agentName,
+    ...job.kind === "changes" && job.publicationId ? { publicationId: job.publicationId } : {},
     changesBySessionId: /* @__PURE__ */ new Map(),
     removedSessionIds: /* @__PURE__ */ new Set(),
     meta: {},
@@ -1484,7 +2275,11 @@ function createPendingChanges(job) {
   };
 }
 function mergeChanges(pending, job) {
+  pending.kind = job.kind;
   pending.context = job.context;
+  if (job.kind === "changes" && job.publicationId) {
+    pending.publicationId = job.publicationId;
+  }
   pending.searchIndexOptions = mergeSearchIndexOptions(
     pending.searchIndexOptions,
     job.searchIndexOptions
@@ -1511,8 +2306,7 @@ function mergeSearchIndexOptions(current, incoming) {
   return { ...current, ...incoming };
 }
 function changesJobFromPending(pending) {
-  return {
-    kind: "changes",
+  const common = {
     context: pending.context,
     agentName: pending.agentName,
     changes: [...pending.changesBySessionId.values()],
@@ -1520,6 +2314,11 @@ function changesJobFromPending(pending) {
     meta: pending.meta,
     ...pending.searchIndexOptions ? { searchIndexOptions: pending.searchIndexOptions } : {}
   };
+  return pending.kind === "changes" ? {
+    kind: "changes",
+    ...common,
+    ...pending.publicationId ? { publicationId: pending.publicationId } : {}
+  } : { kind: "maintenance", ...common };
 }
 
 // src/search-index-job-runner.ts
@@ -1529,13 +2328,20 @@ var SearchIndexJobRunner = class {
   activeBatch = null;
   nextBatchId = 1;
   pendingJobs = new PendingSearchIndexJobs();
+  pendingMaintenanceJobs = new PendingSearchIndexJobs();
   isShuttingDown = false;
-  enqueue(context, jobs) {
+  enqueue(context, jobs, onStarted) {
+    return this.enqueueIn(this.pendingJobs, context, jobs, onStarted);
+  }
+  enqueueMaintenance(context, jobs) {
+    return this.enqueueIn(this.pendingMaintenanceJobs, context, jobs);
+  }
+  enqueueIn(queue, context, jobs, onStarted) {
     if (jobs.length === 0) return Promise.resolve();
     if (this.isShuttingDown) return Promise.reject(new Error(SHUTDOWN_ERROR_MESSAGE));
     const batchId = this.nextBatchId++;
-    const completion = this.pendingJobs.enqueue(batchId, context, jobs);
-    if (this.worker) {
+    const completion = queue.enqueue(batchId, context, jobs, onStarted);
+    if (this.activeBatch) {
       const snapshot = this.snapshot();
       appLogger.debug("search_index.worker_queued", {
         batch_id: batchId,
@@ -1555,7 +2361,9 @@ var SearchIndexJobRunner = class {
       activeBatchId: this.activeBatch?.id,
       pendingBatches: this.pendingJobs.batchCount,
       pendingJobs: this.pendingJobs.jobCount,
-      pendingChanges: this.pendingJobs.changeCount
+      pendingChanges: this.pendingJobs.changeCount,
+      pendingMaintenanceBatches: this.pendingMaintenanceJobs.batchCount,
+      pendingMaintenanceJobs: this.pendingMaintenanceJobs.jobCount
     };
   }
   async shutdown() {
@@ -1567,17 +2375,25 @@ var SearchIndexJobRunner = class {
     const shutdownError = new Error(SHUTDOWN_ERROR_MESSAGE);
     if (activeBatch) this.settle(activeBatch, shutdownError);
     this.pendingJobs.rejectAll(shutdownError);
+    this.pendingMaintenanceJobs.rejectAll(shutdownError);
     if (worker) await worker.terminate();
   }
   startNextBatch() {
-    if (this.isShuttingDown || this.worker) return;
-    const batch = this.pendingJobs.take();
+    if (this.isShuttingDown || this.activeBatch) return;
+    const batch = this.pendingJobs.take() ?? this.pendingMaintenanceJobs.take();
     if (!batch) return;
     appLogger.info("search_index.worker_dequeued", {
       batch_id: batch.id,
       context: batch.context,
       pending_batches: this.pendingJobs.batchCount
     });
+    batch.start((error) => {
+      appLogger.error("search_index.worker_start_listener_failed", {
+        batch_id: batch.id,
+        context: batch.context,
+        error: toError(error)
+      });
+    });
     this.startBatch(batch);
   }
   startBatch(batch) {
@@ -1585,10 +2401,27 @@ var SearchIndexJobRunner = class {
       this.settle(batch, new Error(SHUTDOWN_ERROR_MESSAGE));
       return;
     }
+    const request = {
+      type: "run",
+      pricingGenerationId: getPricingGeneration().id,
+      context: batch.context,
+      jobs: batch.jobs
+    };
+    const existingWorker = this.worker;
+    if (existingWorker) {
+      this.activeBatch = batch;
+      try {
+        existingWorker.postMessage(request);
+      } catch (error) {
+        this.invalidateWorker(existingWorker, toError(error));
+      }
+      return;
+    }
     const workerUrl = this.workerUrl();
     if (!workerUrl) {
       appLogger.warn("search_index.worker_missing", { context: batch.context });
-      this.settle(batch);
+      this.settle(batch, new Error("Search index worker is unavailable"));
+      this.startNextBatch();
       return;
     }
     appLogger.info("search_index.worker_started", {
@@ -1596,33 +2429,37 @@ var SearchIndexJobRunner = class {
       context: batch.context,
       jobs: batch.jobs.length
     });
-    const worker = new Worker(workerUrl, {
-      workerData: {
-        context: batch.context,
-        jobs: batch.jobs,
-        agentNames: [],
-        sessionsByAgent: {},
-        metaByAgent: {}
-      }
-    });
+    let worker;
+    try {
+      worker = new Worker(workerUrl, { workerData: request });
+    } catch (error) {
+      this.settle(batch, toError(error));
+      this.startNextBatch();
+      return;
+    }
     worker.unref();
     this.worker = worker;
     this.activeBatch = batch;
     worker.on("message", (message) => {
+      if (appLogger.consumeWorkerMessage(message)) return;
+      if (this.worker !== worker) return;
+      const activeBatch = this.activeBatch;
+      if (!activeBatch) return;
       if (message.type === "sync-result") {
         logSearchIndexSync(message.context, message.result);
         return;
       }
       if (message.type === "persist-failed") {
         appLogger.error("search_index.persist_failed", {
-          batch_id: batch.id,
+          batch_id: activeBatch.id,
           context: message.context,
           stage: message.stage,
+          publication_id: message.publicationId,
           agent: message.agentName,
           sessions: message.sessions
         });
-        this.settle(
-          batch,
+        this.finishBatch(
+          activeBatch,
           new Error(
             `Search index worker failed to persist ${message.stage} for ${message.agentName}`
           )
@@ -1634,30 +2471,56 @@ var SearchIndexJobRunner = class {
         duration_ms: Math.round(message.durationMs),
         sessions: message.sessions
       });
-      this.settle(batch);
+      this.finishBatch(activeBatch);
     });
     worker.on("error", (error) => {
-      appLogger.error("search_index.worker_error", { context: batch.context, error });
-      this.settle(batch, error);
+      appLogger.error("search_index.worker_error", {
+        context: this.activeBatch?.context ?? batch.context,
+        error
+      });
+      this.invalidateWorker(worker, toError(error));
     });
-    worker.on("exit", (code) => this.finishWorker(worker, batch, code));
+    worker.on("exit", (code) => this.finishWorker(worker, code));
+  }
+  finishBatch(batch, error) {
+    if (this.activeBatch !== batch) return;
+    this.activeBatch = null;
+    this.settle(batch, error);
+    this.startNextBatch();
+  }
+  invalidateWorker(worker, error) {
+    if (this.worker !== worker) return;
+    this.worker = null;
+    const batch = this.activeBatch;
+    this.activeBatch = null;
+    if (batch) this.settle(batch, error);
+    void worker.terminate();
+    this.startNextBatch();
   }
-  finishWorker(worker, batch, code) {
+  finishWorker(worker, code) {
+    const batch = this.worker === worker ? this.activeBatch : null;
     appLogger.info("search_index.worker_exited", {
-      batch_id: batch.id,
-      context: batch.context,
+      batch_id: batch?.id,
+      context: batch?.context,
       code,
       shutting_down: this.isShuttingDown || void 0
     });
-    if (this.worker === worker) this.worker = null;
-    if (this.activeBatch === batch) this.activeBatch = null;
-    const error = code === 0 ? new Error("Search index worker exited before completing its batch") : new Error(`Search index worker exited with code ${code}`);
-    if (code !== 0) appLogger.warn("search_index.worker_exit", { context: batch.context, code });
-    this.settle(batch, error);
+    if (this.worker !== worker) return;
+    this.worker = null;
+    this.activeBatch = null;
+    if (batch) {
+      const error = code === 0 ? new Error("Search index worker exited before completing its batch") : new Error(`Search index worker exited with code ${code}`);
+      if (code !== 0) {
+        appLogger.warn("search_index.worker_exit", { context: batch.context, code });
+      }
+      this.settle(batch, error);
+    }
     this.startNextBatch();
   }
   settle(batch, error) {
-    if (!this.pendingJobs.settle(batch, error)) return;
+    if (!this.pendingJobs.settle(batch, error) && !this.pendingMaintenanceJobs.settle(batch, error)) {
+      return;
+    }
     appLogger.info("search_index.worker_settled", {
       batch_id: batch.id,
       context: batch.context,
@@ -1671,6 +2534,143 @@ var SearchIndexJobRunner = class {
   }
 };
 
+// src/search-index-maintenance-scheduler.ts
+var MAINTENANCE_BATCH_SIZE = 4;
+var SearchIndexMaintenanceScheduler = class {
+  constructor(runner, onStatus) {
+    this.runner = runner;
+    this.onStatus = onStatus;
+  }
+  runner;
+  onStatus;
+  pendingAgents = /* @__PURE__ */ new Set();
+  completedAgents = /* @__PURE__ */ new Set();
+  failedAgents = /* @__PURE__ */ new Set();
+  cachedSessionsByAgent = /* @__PURE__ */ new Map();
+  currentAgent;
+  remaining;
+  pumpPromise = null;
+  stopped = false;
+  enqueue(agentName) {
+    if (this.stopped) return;
+    this.pendingAgents.add(agentName);
+    this.completedAgents.delete(agentName);
+    this.failedAgents.delete(agentName);
+    this.cachedSessionsByAgent.delete(agentName);
+    this.startPump();
+  }
+  stop() {
+    this.stopped = true;
+    this.pendingAgents.clear();
+    this.cachedSessionsByAgent.clear();
+    this.publishStatus();
+  }
+  async waitForIdle() {
+    while (this.pumpPromise) await this.pumpPromise;
+  }
+  startPump() {
+    if (this.pumpPromise || this.stopped) return;
+    this.pumpPromise = this.pump().finally(() => {
+      this.pumpPromise = null;
+      if (this.pendingAgents.size > 0 && !this.stopped) this.startPump();
+    });
+  }
+  async pump() {
+    while (!this.stopped && this.pendingAgents.size > 0) {
+      const agentName = this.pendingAgents.values().next().value;
+      this.pendingAgents.delete(agentName);
+      this.currentAgent = agentName;
+      try {
+        await this.runBatch(agentName);
+      } catch (error) {
+        this.cachedSessionsByAgent.delete(agentName);
+        if (!this.stopped) {
+          this.failedAgents.add(agentName);
+          appLogger.error("search_index.maintenance_failed", {
+            agent: agentName,
+            error: toError(error)
+          });
+        }
+      } finally {
+        this.currentAgent = void 0;
+        this.remaining = void 0;
+        this.publishStatus();
+      }
+    }
+  }
+  async runBatch(agentName) {
+    const pending = readPendingSearchIndexMaintenance(agentName, MAINTENANCE_BATCH_SIZE);
+    if (!pending) throw new Error("Search index storage is unavailable");
+    if (pending.total === 0) {
+      this.completedAgents.add(agentName);
+      return;
+    }
+    this.remaining = pending.total;
+    this.publishStatus();
+    const cached = this.cachedSessionsByAgent.get(agentName) ?? loadCachedSessions(agentName);
+    if (!cached) throw new Error(`Session cache is unavailable for ${agentName}`);
+    this.cachedSessionsByAgent.set(agentName, cached);
+    const sessionsById = new Map(
+      cached.sessions.map((session, sortIndex) => [session.id, { session, sortIndex }])
+    );
+    const changes = pending.sessionIds.flatMap((sessionId) => {
+      const change = sessionsById.get(sessionId);
+      return change ? [change] : [];
+    });
+    if (changes.length === 0) {
+      throw new Error(`No cached sessions matched pending maintenance for ${agentName}`);
+    }
+    const meta = Object.fromEntries(
+      changes.flatMap(({ session }) => {
+        const sessionMeta = cached.meta[session.id];
+        return sessionMeta ? [[session.id, sessionMeta]] : [];
+      })
+    );
+    const job = {
+      kind: "maintenance",
+      context: "search.maintenance",
+      agentName,
+      changes,
+      removedSessionIds: [],
+      meta,
+      searchIndexOptions: { isBulk: false }
+    };
+    appLogger.info("search_index.maintenance_batch_started", {
+      agent: agentName,
+      batch_sessions: changes.length,
+      remaining: pending.total
+    });
+    await this.runner.enqueueMaintenance("search.maintenance", [job]);
+    const next = readPendingSearchIndexMaintenance(agentName, MAINTENANCE_BATCH_SIZE);
+    if (!next) throw new Error("Search index storage became unavailable");
+    if (next.total >= pending.total) {
+      throw new Error(`Search index maintenance made no progress for ${agentName}`);
+    }
+    appLogger.info("search_index.maintenance_batch_completed", {
+      agent: agentName,
+      indexed: pending.total - next.total,
+      remaining: next.total
+    });
+    if (next.total > 0) {
+      this.pendingAgents.add(agentName);
+      this.remaining = next.total;
+      return;
+    }
+    this.cachedSessionsByAgent.delete(agentName);
+    this.completedAgents.add(agentName);
+  }
+  publishStatus() {
+    this.onStatus({
+      active: this.currentAgent != null || this.pendingAgents.size > 0,
+      pendingAgents: [...this.pendingAgents],
+      ...this.currentAgent ? { currentAgent: this.currentAgent } : {},
+      ...this.remaining != null ? { remaining: this.remaining } : {},
+      completedAgents: [...this.completedAgents],
+      failedAgents: [...this.failedAgents]
+    });
+  }
+};
+
 // src/scan-status-model.ts
 var ScanStatusModel = class {
   status = {
@@ -1682,7 +2682,13 @@ var ScanStatusModel = class {
     agentStatuses: {},
     totalAgents: 0,
     updatedAt: Date.now(),
-    backfill: { active: false, pendingAgents: [], completedAgents: [], failedAgents: [] }
+    backfill: { active: false, pendingAgents: [], completedAgents: [], failedAgents: [] },
+    searchIndexMaintenance: {
+      active: false,
+      pendingAgents: [],
+      completedAgents: [],
+      failedAgents: []
+    }
   };
   snapshot() {
     const backfill = {
@@ -1708,7 +2714,13 @@ var ScanStatusModel = class {
           { ...status }
         ])
       ),
-      backfill
+      backfill,
+      searchIndexMaintenance: {
+        ...this.status.searchIndexMaintenance,
+        pendingAgents: [...this.status.searchIndexMaintenance.pendingAgents],
+        completedAgents: [...this.status.searchIndexMaintenance.completedAgents],
+        failedAgents: [...this.status.searchIndexMaintenance.failedAgents]
+      }
     };
   }
   startBatch(agentNames, phase, sessionCounts) {
@@ -1778,7 +2790,7 @@ var ScanStatusModel = class {
   }
   updateAgent(agentName, progress) {
     const status = this.status.agentStatuses[agentName];
-    if (!status || status.status === "pending" || status.status === "complete" || status.status === "indexing" && progress.phase !== "finalizing") {
+    if (!status || status.status === "pending" || status.status === "complete" || (status.status === "publish-queued" || status.status === "publishing") && progress.phase !== "finalizing") {
       return null;
     }
     const now = Date.now();
@@ -1801,7 +2813,7 @@ var ScanStatusModel = class {
       updatedAt: now
     });
   }
-  indexAgent(agentName) {
+  queueAgentPublication(agentName) {
     const status = this.status.agentStatuses[agentName];
     if (!this.status.active || !status || status.status !== "scanning" && status.status !== "finalizing") {
       return null;
@@ -1809,7 +2821,24 @@ var ScanStatusModel = class {
     const now = Date.now();
     const agentStatuses = {
       ...this.status.agentStatuses,
-      [agentName]: { ...status, status: "indexing", updatedAt: now }
+      [agentName]: { ...status, status: "publish-queued", updatedAt: now }
+    };
+    return this.set({
+      ...this.status,
+      phase: this.activePhase(this.status.pendingAgents, this.status.scanningAgents, agentStatuses),
+      agentStatuses,
+      updatedAt: now
+    });
+  }
+  publishAgent(agentName) {
+    const status = this.status.agentStatuses[agentName];
+    if (!this.status.active || !status || status.status !== "scanning" && status.status !== "finalizing" && status.status !== "publish-queued") {
+      return null;
+    }
+    const now = Date.now();
+    const agentStatuses = {
+      ...this.status.agentStatuses,
+      [agentName]: { ...status, status: "publishing", updatedAt: now }
     };
     return this.set({
       ...this.status,
@@ -1851,6 +2880,38 @@ var ScanStatusModel = class {
       completedAt: isActive ? void 0 : now
     });
   }
+  failAgent(agentName, error, sessionCount) {
+    const pendingAgents = this.status.pendingAgents.filter((agent) => agent !== agentName);
+    const scanningAgents = this.status.scanningAgents.filter((agent) => agent !== agentName);
+    const completedAgents = this.status.completedAgents.filter((agent) => agent !== agentName);
+    const isActive = pendingAgents.length > 0 || scanningAgents.length > 0;
+    const now = Date.now();
+    const previousStatus = this.status.agentStatuses[agentName];
+    return this.set({
+      ...this.status,
+      active: isActive,
+      phase: isActive ? this.activePhase(pendingAgents, scanningAgents, this.status.agentStatuses) : "idle",
+      pendingAgents,
+      scanningAgents,
+      completedAgents,
+      agentStatuses: {
+        ...this.status.agentStatuses,
+        [agentName]: {
+          agentName,
+          status: "failed",
+          error,
+          total: previousStatus?.total,
+          processed: previousStatus?.processed,
+          sessions: sessionCount ?? previousStatus?.sessions ?? 0,
+          startedAt: previousStatus?.startedAt,
+          updatedAt: now,
+          completedAt: now
+        }
+      },
+      updatedAt: now,
+      completedAt: isActive ? void 0 : now
+    });
+  }
   finishBatch() {
     const now = Date.now();
     return this.set({
@@ -1862,26 +2923,49 @@ var ScanStatusModel = class {
       agentStatuses: Object.fromEntries(
         Object.entries(this.status.agentStatuses).map(([agentName, status]) => [
           agentName,
-          { ...status, status: "complete", completedAt: status.completedAt ?? now, updatedAt: now }
+          status.status === "failed" ? { ...status, completedAt: status.completedAt ?? now, updatedAt: now } : {
+            ...status,
+            status: "complete",
+            completedAt: status.completedAt ?? now,
+            updatedAt: now
+          }
         ])
       ),
       updatedAt: now,
       completedAt: now
     });
   }
-  updateBackfill(patch) {
+  updateBackfill(backfill) {
+    return this.set({
+      ...this.status,
+      backfill: {
+        ...backfill,
+        pendingAgents: [...backfill.pendingAgents],
+        completedAgents: [...backfill.completedAgents],
+        failedAgents: [...backfill.failedAgents],
+        progress: backfill.progress ? { ...backfill.progress } : void 0
+      },
+      updatedAt: Date.now()
+    });
+  }
+  updateSearchIndexMaintenance(searchIndexMaintenance) {
     return this.set({
       ...this.status,
-      backfill: { ...this.status.backfill, ...patch },
+      searchIndexMaintenance: {
+        ...searchIndexMaintenance,
+        pendingAgents: [...searchIndexMaintenance.pendingAgents],
+        completedAgents: [...searchIndexMaintenance.completedAgents],
+        failedAgents: [...searchIndexMaintenance.failedAgents]
+      },
       updatedAt: Date.now()
     });
   }
   activePhase(pendingAgents, scanningAgents, agentStatuses) {
     if (pendingAgents.length === 0 && scanningAgents.length > 0 && scanningAgents.every((agentName) => {
       const status = agentStatuses[agentName]?.status;
-      return status === "finalizing" || status === "indexing";
+      return status === "finalizing" || status === "publish-queued" || status === "publishing";
     })) {
-      return "indexing";
+      return "publishing";
     }
     return this.status.phase === "initializing" ? "initializing" : "scanning";
   }
@@ -1897,14 +2981,26 @@ var EMPTY_AGENT_REFRESH_DEBOUNCE_MS = 3e4;
 var SEARCH_INDEX_BULK_PENDING_PATH_THRESHOLD = 100;
 var BACKFILL_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 var CACHE_TRUNCATION_COVERAGE = 0.5;
-function buildPersistenceDiff(previousSessions, nextSessions, candidateChangedIds = []) {
+var STATUS_PROGRESS_INTERVAL_MS = 100;
+function buildPersistenceDiff(previousSessions, nextSessions, candidateChangedIds = [], completeness = "complete", explicitRemovedSessionIds = []) {
   const { changes, removedSessionIds } = computeSessionDiff(
     previousSessions,
     nextSessions,
     candidateChangedIds,
     sessionSignature
   );
-  return { changedSessions: changes, removedSessionIds };
+  if (completeness === "complete") {
+    return { changedSessions: changes, removedSessionIds };
+  }
+  const explicitRemovals = new Set(explicitRemovedSessionIds);
+  return {
+    changedSessions: changes,
+    removedSessionIds: removedSessionIds.filter((sessionId) => explicitRemovals.has(sessionId))
+  };
+}
+function sourceFailureError(failures) {
+  const noun = failures.length === 1 ? "source" : "sources";
+  return new Error(`${failures.length} session ${noun} failed; last-known-good data retained`);
 }
 function restoreAgentCacheMeta(agent, cached) {
   agent.setSessionMetaMap(new Map(Object.entries(cached.meta)));
@@ -1913,21 +3009,24 @@ var AgentSyncEngine = class {
   constructor(options) {
     this.options = options;
     this.scheduler = new AgentOperationScheduler((agentName) => this.performRefresh(agentName));
+    this.searchIndexJobs = new SearchIndexJobRunner();
+    this.searchIndexMaintenance = new SearchIndexMaintenanceScheduler(
+      this.searchIndexJobs,
+      (status) => this.publishStatus(this.scanStatus.updateSearchIndexMaintenance(status))
+    );
   }
   options;
   lastRefreshAtByAgent = /* @__PURE__ */ new Map();
   scheduler;
   sessionIndex = new LiveSessionIndex();
-  backfillQueue = [];
-  currentBackfillAgent;
-  currentBackfillProgress;
-  cacheIntegrityCheckedAgents = /* @__PURE__ */ new Set();
-  completedBackfillAgents = [];
-  failedBackfillAgents = [];
+  backfills = new BackfillLifecycle();
+  cacheIntegrityValidUntilByAgent = /* @__PURE__ */ new Map();
   sessionsChangedListeners = /* @__PURE__ */ new Set();
   statusChangedListeners = /* @__PURE__ */ new Set();
+  statusProgressThrottles = /* @__PURE__ */ new Map();
   scanStatus = new ScanStatusModel();
-  searchIndexJobs = new SearchIndexJobRunner();
+  searchIndexJobs;
+  searchIndexMaintenance;
   nextPublicationId = 1;
   backgroundRefreshTimer = null;
   isShuttingDown = false;
@@ -1940,6 +3039,13 @@ var AgentSyncEngine = class {
         options.cacheTimestamps?.[agent.name] ?? Date.now()
       );
     }
+    for (const [agentName, failure] of Object.entries(snapshot.scanFailures ?? {})) {
+      this.scanStatus.failAgent(
+        agentName,
+        `${failure.stage}: ${failure.message}`,
+        snapshot.byAgent[agentName]?.length ?? 0
+      );
+    }
   }
   snapshot() {
     return this.sessionIndex.snapshot();
@@ -1961,6 +3067,7 @@ var AgentSyncEngine = class {
       publicationId: this.publicationId("scan.initial"),
       agents: jobs.map((job) => job.agentName)
     });
+    for (const job of jobs) this.searchIndexMaintenance.enqueue(job.agentName);
   }
   handleAgentsChanged(agentNames) {
     const snapshot = this.sessionIndex.snapshot();
@@ -1988,7 +3095,7 @@ var AgentSyncEngine = class {
     const activeOperations = {
       agent_operations: schedulerSnapshot.activeOperations,
       refreshes: schedulerSnapshot.activeRefreshes,
-      backfill_running: this.currentBackfillAgent != null || void 0,
+      backfill_running: this.backfills.runningAttempt()?.agentName || void 0,
       scan_workers: this.options.workerRunner.activeCount
     };
     if (activeOperations.agent_operations > 0 || activeOperations.scan_workers > 0) {
@@ -1999,16 +3106,17 @@ var AgentSyncEngine = class {
       clearTimeout(this.backgroundRefreshTimer);
       this.backgroundRefreshTimer = null;
     }
-    this.backfillQueue.length = 0;
-    this.currentBackfillAgent = void 0;
-    this.currentBackfillProgress = void 0;
-    this.cacheIntegrityCheckedAgents.clear();
+    this.backfills.cancelAll();
+    this.searchIndexMaintenance.stop();
+    this.cancelProgressStatuses();
+    this.cacheIntegrityValidUntilByAgent.clear();
     const searchIndexSnapshot = this.searchIndexJobs.snapshot();
     appLogger.info("search_index.shutdown.started", {
       active_batch_id: searchIndexSnapshot.activeBatchId,
       pending_batches: searchIndexSnapshot.pendingBatches
     });
     await this.searchIndexJobs.shutdown();
+    await this.searchIndexMaintenance.waitForIdle();
     await this.options.workerRunner.shutdown();
     await this.scheduler.waitForIdle();
     const stoppedSearchIndexSnapshot = this.searchIndexJobs.snapshot();
@@ -2028,41 +3136,106 @@ var AgentSyncEngine = class {
     this.publishStatus(this.scanStatus.setPhase(phase));
   }
   beginAgentScan(agentName) {
+    this.cancelProgressStatus(`scan:${agentName}`);
     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)
     );
   }
-  updateAgentScanProgress(agentName, progress) {
-    if (this.currentBackfillAgent === agentName) {
-      this.currentBackfillProgress = {
+  updateAgentScanProgress(agentName, progress, backfillAttempt) {
+    if (backfillAttempt) {
+      const key2 = `backfill:${agentName}`;
+      const current = this.backfills.stateFor(agentName);
+      if (current?.status !== "running" || current.attemptId !== backfillAttempt.attemptId) {
+        return;
+      }
+      const currentPhase2 = current.progress?.phase ?? "scanning";
+      const nextPhase2 = progress.phase ?? "scanning";
+      if (currentPhase2 && currentPhase2 !== nextPhase2) this.flushProgressStatus(key2);
+      if (this.backfills.updateProgress(backfillAttempt, {
         phase: progress.phase,
         total: progress.total,
         processed: progress.processed,
         sessions: progress.sessions
-      };
-      this.publishBackfillStatus();
+      })) {
+        this.publishProgressStatus(
+          key2,
+          nextPhase2,
+          this.scanStatus.updateBackfill(this.backfills.status())
+        );
+      }
       return;
     }
-    this.publishStatus(this.scanStatus.updateAgent(agentName, progress));
+    const key = `scan:${agentName}`;
+    const currentPhase = this.scanStatus.snapshot().agentStatuses[agentName]?.status;
+    const nextPhase = progress.phase === "finalizing" ? "finalizing" : "scanning";
+    if (currentPhase && currentPhase !== nextPhase) this.flushProgressStatus(key);
+    const status = this.scanStatus.updateAgent(agentName, progress);
+    this.publishProgressStatus(key, status?.agentStatuses[agentName]?.status ?? nextPhase, status);
+  }
+  beginAgentPublishing(agentName) {
+    this.flushProgressStatus(`scan:${agentName}`);
+    this.publishStatus(this.scanStatus.publishAgent(agentName));
   }
-  beginAgentIndexing(agentName) {
-    this.publishStatus(this.scanStatus.indexAgent(agentName));
+  queueAgentPublication(agentName) {
+    this.flushProgressStatus(`scan:${agentName}`);
+    this.publishStatus(this.scanStatus.queueAgentPublication(agentName));
   }
   finishAgentScan(agentName) {
+    this.flushProgressStatus(`scan:${agentName}`);
     const count = this.sessionIndex.snapshot().byAgent[agentName]?.length;
     this.publishStatus(this.scanStatus.finishAgent(agentName, count));
   }
   finishScanBatch() {
+    this.flushProgressStatuses("scan:");
     this.publishStatus(this.scanStatus.finishBatch());
   }
   publishBackfillStatus() {
-    this.publishStatus(this.scanStatus.updateBackfill(this.backfillStatus()));
+    this.publishStatus(this.scanStatus.updateBackfill(this.backfills.status()));
   }
   publishStatus(event) {
     if (!event || this.isShuttingDown) return;
-    for (const listener of this.statusChangedListeners) listener(event);
+    for (const listener of this.statusChangedListeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        appLogger.error("scan.status_listener.error", { error });
+      }
+    }
+  }
+  publishProgressStatus(key, phase, event) {
+    if (!event) return;
+    let throttle = this.statusProgressThrottles.get(key);
+    if (!throttle) {
+      throttle = new LatestValueThrottle(STATUS_PROGRESS_INTERVAL_MS, () => {
+        this.publishStatus(this.scanStatus.snapshot());
+      });
+      this.statusProgressThrottles.set(key, throttle);
+    }
+    throttle.push(void 0, phase);
+  }
+  flushProgressStatus(key) {
+    const throttle = this.statusProgressThrottles.get(key);
+    if (!throttle) return;
+    throttle.flush();
+    throttle.cancel();
+    this.statusProgressThrottles.delete(key);
+  }
+  cancelProgressStatus(key) {
+    const throttle = this.statusProgressThrottles.get(key);
+    if (!throttle) return;
+    throttle.cancel();
+    this.statusProgressThrottles.delete(key);
+  }
+  flushProgressStatuses(prefix) {
+    for (const key of this.statusProgressThrottles.keys()) {
+      if (key.startsWith(prefix)) this.flushProgressStatus(key);
+    }
+  }
+  cancelProgressStatuses() {
+    for (const throttle of this.statusProgressThrottles.values()) throttle.cancel();
+    this.statusProgressThrottles.clear();
   }
   emitSessionsChanged(change) {
     if (this.isShuttingDown) return;
@@ -2070,20 +3243,33 @@ var AgentSyncEngine = class {
   }
   async performRefresh(agentName) {
     this.beginAgentScan(agentName);
+    const startedAt = performance.now();
+    let failed = false;
+    let cached = null;
+    let result = null;
     try {
-      return await this.runRefresh(agentName);
+      if (this.findAgent(agentName)) cached = loadCachedSessions(agentName);
+      result = await this.runRefresh(agentName, cached, startedAt);
+      return result;
     } catch (error) {
+      this.options.workerRunner.discard?.(agentName);
+      failed = true;
+      const failure = toError(error);
       appLogger.error("scan.refresh.error", { agent: agentName, error });
       console.error(`[${agentName}] Session refresh failed:`, error);
+      this.flushProgressStatus(`scan:${agentName}`);
+      this.publishStatus(this.scanStatus.failAgent(agentName, failure.message));
       return "failed";
     } finally {
-      this.finishAgentScan(agentName);
+      if (!failed) this.finishAgentScan(agentName);
       const agent = this.findAgent(agentName);
-      if (agent && this.needsBackfill(agent)) this.enqueueBackfill(agentName);
+      if (agent && this.needsBackfill(agent, cached, failed || result === "committed")) {
+        this.enqueueBackfill(agentName);
+      }
+      if (agent) this.searchIndexMaintenance.enqueue(agentName);
     }
   }
-  async runRefresh(agentName) {
-    const startedAt = performance.now();
+  async runRefresh(agentName, cached, startedAt) {
     const pendingPathCount = this.scheduler.takePendingSignalCount(agentName);
     const agent = this.findAgent(agentName);
     if (!agent) {
@@ -2091,11 +3277,20 @@ var AgentSyncEngine = class {
       return "skipped";
     }
     const previousSessions = this.sessionIndex.snapshot().byAgent[agentName] ?? [];
-    const cached = loadCachedSessions(agentName);
     const refreshBaseline = cached?.sessions ?? previousSessions;
     const cacheTimestamp = cached?.timestamp ?? this.lastRefreshAtByAgent.get(agentName) ?? 0;
     if (cached) restoreAgentCacheMeta(agent, cached);
-    const isInitialized = isAgentCacheInitialized(agentName);
+    const durableMeta = new Map(agent.getSessionMetaMap());
+    const durableLastRefreshAt = this.lastRefreshAtByAgent.get(agentName);
+    const initialization = readAgentCacheInitialization(agentName);
+    if (initialization.status === "failed") {
+      appLogger.warn("scan.refresh.cache_state_unavailable", {
+        agent: agentName,
+        state: "initialization"
+      });
+      return "unchanged";
+    }
+    const isInitialized = initialization.value;
     const availabilityStartedAt = performance.now();
     const isAvailable = agent.isAvailable();
     const availabilityDuration = performance.now() - availabilityStartedAt;
@@ -2116,10 +3311,29 @@ var AgentSyncEngine = class {
     } else {
       strategyResult = await this.scanAgentFully(agent, previousSessions);
     }
-    if (strategyResult.status === "unchanged") return "unchanged";
+    if (strategyResult.status === "unchanged") {
+      this.options.workerRunner.commit?.(agentName);
+      return "unchanged";
+    }
     const nextSessions = attachMissingProjectIdentities(strategyResult.nextSessions);
     const searchIndexOptions = pendingPathCount >= SEARCH_INDEX_BULK_PENDING_PATH_THRESHOLD ? { isBulk: true } : void 0;
     const persistenceDiff = strategyResult.persistenceDiff;
+    const publicationSessions = strategyResult.fullScanSessions ?? nextSessions;
+    const publicationSessionIds = new Set(publicationSessions.map((session) => session.id));
+    const missingBaselineSessions = refreshBaseline.reduce(
+      (count, session) => count + Number(!publicationSessionIds.has(session.id)),
+      0
+    );
+    const replacementDeleteCandidates = persistenceDiff ? persistenceDiff.removedSessionIds.length : strategyResult.completeness === "complete" ? missingBaselineSessions : strategyResult.explicitRemovedSessionIds.length;
+    appLogger.info("scan.refresh.persistence_candidate", {
+      agent: agentName,
+      scope_from: strategyResult.scope.from,
+      scope_to: strategyResult.scope.to,
+      publication_completeness: strategyResult.completeness,
+      durable_baseline_sessions: refreshBaseline.length,
+      payload_sessions: publicationSessions.length,
+      delete_candidates: replacementDeleteCandidates
+    });
     const changedSessionIds = persistenceDiff ? new Set(persistenceDiff.changedSessions.map(({ session }) => session.id)) : void 0;
     const persistStartedAt = performance.now();
     const persistentJob = persistenceDiff ? {
@@ -2134,39 +3348,62 @@ var AgentSyncEngine = class {
       kind: "full",
       context: "scan.refresh",
       agentName,
-      sessions: strategyResult.fullScanSessions ?? nextSessions,
+      sessions: publicationSessions,
       meta: buildAgentCacheMeta(agent),
+      completeness: strategyResult.completeness,
+      removedSessionIds: strategyResult.explicitRemovedSessionIds,
       saveCache: true,
       ...searchIndexOptions ? { searchIndexOptions } : {}
     };
-    this.beginAgentIndexing(agentName);
-    const publication = await this.commitSessionPublication({
-      context: "scan.refresh",
-      agentName,
-      sessions: nextSessions,
-      candidateChangedIds: strategyResult.preciseChangedIds ?? [],
-      indexJob: persistentJob
-    });
+    this.queueAgentPublication(agentName);
+    let publication;
+    try {
+      publication = await this.commitSessionPublication({
+        context: "scan.refresh",
+        agentName,
+        sessions: nextSessions,
+        candidateChangedIds: strategyResult.preciseChangedIds ?? [],
+        indexJob: persistentJob,
+        onPublishing: () => this.beginAgentPublishing(agentName)
+      });
+    } catch (error) {
+      agent.setSessionMetaMap(durableMeta);
+      if (durableLastRefreshAt == null) this.lastRefreshAtByAgent.delete(agentName);
+      else this.lastRefreshAtByAgent.set(agentName, durableLastRefreshAt);
+      throw error;
+    }
+    this.options.workerRunner.commit?.(agentName);
     const persistDuration = performance.now() - persistStartedAt;
     logSearchIndexSync("scan.refresh", null, { pending_paths: pendingPathCount });
     const totalDurationMs = performance.now() - startedAt;
     this.scheduler.recordRefreshDuration(agentName, totalDurationMs);
-    appLogger.info("scan.refresh.done", {
-      agent: agentName,
-      duration_ms: Math.round(totalDurationMs),
-      sessions: nextSessions.length,
-      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(publication.diffDuration),
-      persist_ms: Math.round(persistDuration),
-      search_index_ms: Math.round(persistDuration),
-      persistent_index_worker_job: persistentJob.kind
-    });
+    appLogger.info(
+      strategyResult.sourceFailures.length > 0 ? "scan.refresh.partial" : "scan.refresh.done",
+      {
+        agent: agentName,
+        duration_ms: Math.round(totalDurationMs),
+        sessions: nextSessions.length,
+        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(publication.diffDuration),
+        persist_ms: Math.round(persistDuration),
+        search_index_ms: Math.round(persistDuration),
+        persistent_index_worker_job: persistentJob.kind,
+        failed_sources: strategyResult.sourceFailures.length
+      }
+    );
+    if (strategyResult.sourceFailures.length > 0) {
+      appLogger.warn("scan.refresh.source_failures", {
+        agent: agentName,
+        failures: strategyResult.sourceFailures
+      });
+      throw sourceFailureError(strategyResult.sourceFailures);
+    }
     return "committed";
   }
   /**
@@ -2183,28 +3420,29 @@ var AgentSyncEngine = class {
         agent: agentName,
         retained_sessions: previousSessions.length
       });
-      return this.refreshStrategyResult(previousSessions, { status: "unchanged" });
+      return this.refreshStrategyResult(previousSessions, "partial", {}, { status: "unchanged" });
     }
-    return this.refreshStrategyResult([]);
+    return this.refreshStrategyResult([], "partial", {});
   }
   async initializeAgent(agent, previousSessions) {
     this.setScanPhase("initializing");
     const scanStartedAt = performance.now();
-    const result = await this.runWorker(agent, previousSessions, null, this.startupScanOptions(), {
-      checkpoint: true
-    });
+    const scope = this.startupScanOptions();
+    const result = await this.runWorker(agent, previousSessions, { kind: "full-scan" }, scope);
     agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
     const sessions = attachMissingProjectIdentities(result.sessions);
     this.lastRefreshAtByAgent.set(agent.name, Date.now());
-    return this.refreshStrategyResult(sessions, {
+    return this.refreshStrategyResult(sessions, result.completeness, scope, {
       fullScanSessions: sessions,
-      scanDuration: performance.now() - scanStartedAt
+      explicitRemovedSessionIds: result.explicitRemovedSessionIds,
+      scanDuration: performance.now() - scanStartedAt,
+      sourceFailures: result.sourceFailures ?? []
     });
   }
   async syncAgentSources(agent, cached, refreshStartedAt) {
     const scanStartedAt = performance.now();
-    const result = await this.runWorker(agent, cached.sessions, null, this.startupScanOptions(), {
-      sourceSync: true,
+    const scope = this.startupScanOptions();
+    const result = await this.runWorker(agent, cached.sessions, { kind: "source-refresh" }, scope, {
       meta: cached.meta
     });
     agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
@@ -2212,62 +3450,130 @@ var AgentSyncEngine = class {
     const preciseChangedIds = result.changedIds ?? [];
     const persistenceDiff = buildPersistenceDiff(cached.sessions, sessions, preciseChangedIds);
     this.lastRefreshAtByAgent.set(agent.name, Date.now());
-    if (persistenceDiff.changedSessions.length === 0 && persistenceDiff.removedSessionIds.length === 0) {
+    if (persistenceDiff.changedSessions.length === 0 && persistenceDiff.removedSessionIds.length === 0 && (result.sourceFailures?.length ?? 0) === 0) {
       this.logUnchangedRefresh(agent.name, refreshStartedAt);
-      return this.refreshStrategyResult(sessions, {
+      return this.refreshStrategyResult(sessions, result.completeness, scope, {
         status: "unchanged",
         scanDuration: performance.now() - scanStartedAt
       });
     }
-    return this.refreshStrategyResult(sessions, {
+    return this.refreshStrategyResult(sessions, result.completeness, scope, {
       preciseChangedIds,
       persistenceDiff,
-      scanDuration: performance.now() - scanStartedAt
+      scanDuration: performance.now() - scanStartedAt,
+      sourceFailures: result.sourceFailures ?? []
     });
   }
   async refreshChangedAgent(agent, baseline, cacheTimestamp, refreshStartedAt) {
+    const scope = this.startupScanOptions();
     const checkStartedAt = performance.now();
     const checkResult = await Promise.resolve(agent.checkForChanges(cacheTimestamp, baseline));
     const checkDuration = performance.now() - checkStartedAt;
+    if (checkResult.status === "failed") {
+      appLogger.warn("scan.refresh.change_check_failed", {
+        agent: agent.name,
+        source_path: checkResult.failure.sourcePath,
+        error_class: checkResult.failure.errorClass,
+        message: checkResult.failure.message
+      });
+      return this.refreshStrategyResult(
+        baseline,
+        "partial",
+        {},
+        { status: "unchanged", checkDuration }
+      );
+    }
     this.lastRefreshAtByAgent.set(agent.name, checkResult.timestamp);
     if (!checkResult.hasChanges) {
-      this.logUnchangedRefresh(agent.name, refreshStartedAt);
-      return this.refreshStrategyResult(baseline, { status: "unchanged", checkDuration });
+      const scanStartedAt2 = performance.now();
+      const result = await this.runWorker(agent, baseline, { kind: "recompute-derived" }, {});
+      agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
+      const sessions2 = attachMissingProjectIdentities(result.sessions);
+      const persistenceDiff = buildPersistenceDiff(baseline, sessions2);
+      if (persistenceDiff.changedSessions.length === 0 && persistenceDiff.removedSessionIds.length === 0) {
+        this.logUnchangedRefresh(agent.name, refreshStartedAt);
+        return this.refreshStrategyResult(
+          sessions2,
+          result.completeness,
+          {},
+          {
+            status: "unchanged",
+            checkDuration,
+            scanDuration: performance.now() - scanStartedAt2
+          }
+        );
+      }
+      return this.refreshStrategyResult(
+        sessions2,
+        result.completeness,
+        {},
+        {
+          persistenceDiff,
+          checkDuration,
+          scanDuration: performance.now() - scanStartedAt2,
+          sourceFailures: result.sourceFailures ?? []
+        }
+      );
     }
     const preciseChangedIds = checkResult.changedIds ?? null;
     const scanStartedAt = performance.now();
     if (preciseChangedIds === null) {
-      const result = await this.runWorker(agent, baseline, null, {}, { checkpoint: true });
+      const result = await this.runWorker(agent, baseline, { kind: "full-scan" }, scope);
       agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
       const sessions2 = attachMissingProjectIdentities(result.sessions);
-      return this.refreshStrategyResult(sessions2, {
-        persistenceDiff: buildPersistenceDiff(baseline, sessions2),
+      return this.refreshStrategyResult(sessions2, result.completeness, scope, {
+        // Meta-only changes (e.g. a pricing capture epoch bump) leave the head
+        // signature intact; without the worker-reported ids they would never
+        // persist and checkForChanges would rescan on every startup.
+        persistenceDiff: buildPersistenceDiff(
+          baseline,
+          sessions2,
+          result.changedIds ?? [],
+          result.completeness,
+          result.explicitRemovedSessionIds
+        ),
         checkDuration,
-        scanDuration: performance.now() - scanStartedAt
+        scanDuration: performance.now() - scanStartedAt,
+        sourceFailures: result.sourceFailures ?? []
       });
     }
+    this.options.workerRunner.discard?.(agent.name);
     const sessions = attachMissingProjectIdentities(
-      await Promise.resolve(agent.incrementalScan(baseline, preciseChangedIds, checkResult.refs))
+      await Promise.resolve(
+        agent.incrementalScan(baseline, preciseChangedIds, checkResult.refs, scope)
+      )
     );
-    return this.refreshStrategyResult(sessions, {
+    const sourceFailures = checkResult.sourceFailures ?? [];
+    const completeness = scope.from == null && scope.to == null && sourceFailures.length === 0 ? "complete" : "partial";
+    return this.refreshStrategyResult(sessions, completeness, scope, {
       preciseChangedIds,
-      persistenceDiff: buildPersistenceDiff(baseline, sessions, preciseChangedIds),
+      persistenceDiff: buildPersistenceDiff(
+        baseline,
+        sessions,
+        preciseChangedIds,
+        completeness,
+        preciseChangedIds
+      ),
       checkDuration,
-      scanDuration: performance.now() - scanStartedAt
+      scanDuration: performance.now() - scanStartedAt,
+      sourceFailures
     });
   }
   async scanAgentFully(agent, previousSessions) {
     const scanStartedAt = performance.now();
-    const result = await this.runWorker(agent, previousSessions, null, {}, { checkpoint: true });
+    const scope = this.startupScanOptions();
+    const result = await this.runWorker(agent, previousSessions, { kind: "full-scan" }, scope);
     agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
     const sessions = attachMissingProjectIdentities(result.sessions);
     this.lastRefreshAtByAgent.set(agent.name, Date.now());
-    return this.refreshStrategyResult(sessions, {
+    return this.refreshStrategyResult(sessions, result.completeness, scope, {
       fullScanSessions: sessions,
-      scanDuration: performance.now() - scanStartedAt
+      explicitRemovedSessionIds: result.explicitRemovedSessionIds,
+      scanDuration: performance.now() - scanStartedAt,
+      sourceFailures: result.sourceFailures ?? []
     });
   }
-  refreshStrategyResult(nextSessions, overrides = {}) {
+  refreshStrategyResult(nextSessions, completeness, scope, overrides = {}) {
     return {
       status: "continue",
       nextSessions,
@@ -2276,86 +3582,55 @@ var AgentSyncEngine = class {
       persistenceDiff: null,
       checkDuration: 0,
       scanDuration: 0,
+      sourceFailures: [],
+      completeness,
+      scope,
+      explicitRemovedSessionIds: [],
       ...overrides
     };
   }
-  runWorker(agent, previousSessions, changedIds, scanOptions, workerOptions = {}) {
+  runWorker(agent, previousSessions, operation, scanOptions, runOptions = {}) {
     return this.options.workerRunner.run(agent.name, {
       previousSessions,
-      changedIds,
+      operation,
       scanOptions,
-      sourceSync: workerOptions.sourceSync,
-      backfill: workerOptions.backfill,
-      backfillCursor: workerOptions.backfillCursor,
-      checkpoint: workerOptions.checkpoint,
-      meta: workerOptions.meta ?? buildAgentCacheMeta(agent),
-      onProgress: (progress) => this.updateAgentScanProgress(agent.name, progress),
-      onCheckpoint: (checkpoint) => this.handleWorkerCheckpoint(agent, checkpoint)
+      meta: runOptions.meta ?? buildAgentCacheMeta(agent),
+      onProgress: (progress) => this.updateAgentScanProgress(agent.name, progress, runOptions.backfillAttempt),
+      onCheckpoint: runOptions.onCheckpoint
     });
   }
-  handleWorkerCheckpoint(agent, checkpoint) {
-    if (this.isShuttingDown) return;
-    if (checkpoint.stage === "scanned") {
-      let persisted2 = false;
-      try {
-        persisted2 = saveCachedSessions(agent.name, checkpoint.sessions, checkpoint.meta);
-        if (persisted2) markAgentCacheInitialized(agent.name);
-      } catch (error) {
-        appLogger.error("scan.checkpoint.failed", {
-          agent: agent.name,
-          stage: checkpoint.stage,
-          error
-        });
-      }
-      agent.setSessionMetaMap(new Map(Object.entries(checkpoint.meta)));
-      const event = this.sessionIndex.commitAgentSessions(agent.name, checkpoint.sessions);
-      this.emitSessionsChanged({
-        agentName: agent.name,
-        sessions: this.sessionIndex.snapshot().byAgent[agent.name] ?? [],
-        event
-      });
-      appLogger.info("scan.checkpoint.persisted", {
-        agent: agent.name,
-        stage: checkpoint.stage,
-        sessions: checkpoint.sessions.length,
-        persisted: persisted2
-      });
-      return;
-    }
-    let persisted = false;
-    try {
-      persisted = saveCachedSessionChanges(agent.name, checkpoint.changes, [], checkpoint.meta);
-    } catch (error) {
-      appLogger.error("scan.checkpoint.failed", {
-        agent: agent.name,
-        stage: checkpoint.stage,
-        sessions: checkpoint.changes.length,
-        error
-      });
-    }
-    if (persisted && checkpoint.backfillCursor) {
-      markAgentFullSyncProgress(agent.name, checkpoint.backfillCursor);
-    }
-    appLogger.debug("scan.checkpoint.persisted", {
-      agent: agent.name,
-      stage: checkpoint.stage,
-      sessions: checkpoint.changes.length,
-      backfill_cursor: checkpoint.backfillCursor,
-      persisted
+  handleBackfillCheckpoint(agentName, checkpoint) {
+    if (checkpoint.stage !== "finalizing" || !checkpoint.backfillCursor) return;
+    markAgentFullSyncProgress(agentName, checkpoint.backfillCursor);
+    appLogger.debug("scan.backfill.checkpoint", {
+      agent: agentName,
+      cursor: checkpoint.backfillCursor,
+      sessions: checkpoint.changes.length
     });
   }
-  needsBackfill(agent) {
+  needsBackfill(agent, cached, reloadCached = false) {
     const startupScanOptions = this.startupScanOptions();
     if (startupScanOptions.from == null && startupScanOptions.to == null) return false;
-    if (!agent.isAvailable()) return false;
-    const lastSyncAt = getAgentLastFullSyncAt(agent.name);
-    if (lastSyncAt == null || Date.now() - lastSyncAt > BACKFILL_INTERVAL_MS) return true;
+    const now = Date.now();
+    if ((this.cacheIntegrityValidUntilByAgent.get(agent.name) ?? 0) >= now) return false;
+    const lastSync = readAgentLastFullSyncAt(agent.name);
+    if (lastSync.status === "failed") {
+      appLogger.warn("scan.backfill.cache_state_unavailable", {
+        agent: agent.name,
+        state: "last_full_sync"
+      });
+      return false;
+    }
+    const lastSyncAt = lastSync.value;
+    if (lastSyncAt == null || now - lastSyncAt > BACKFILL_INTERVAL_MS) {
+      return agent.isAvailable();
+    }
     if (!(agent instanceof FileSystemSessionSource)) return false;
-    if (this.cacheIntegrityCheckedAgents.has(agent.name)) return false;
-    const cached = loadCachedSessions(agent.name);
+    if (!agent.isAvailable()) return false;
+    const cachedSessions = reloadCached || cached === void 0 ? loadCachedSessions(agent.name) : cached;
     const sourceCount = agent.listSessionSources().length;
-    const cachedCount = cached?.sessions.length ?? 0;
-    this.cacheIntegrityCheckedAgents.add(agent.name);
+    const cachedCount = cachedSessions?.sessions.length ?? 0;
+    this.cacheIntegrityValidUntilByAgent.set(agent.name, lastSyncAt + BACKFILL_INTERVAL_MS);
     if (sourceCount > 0 && cachedCount / sourceCount < CACHE_TRUNCATION_COVERAGE) {
       appLogger.warn("scan.backfill.cache_truncated", {
         agent: agent.name,
@@ -2368,43 +3643,45 @@ var AgentSyncEngine = class {
     return false;
   }
   enqueueBackfill(agentName) {
-    if (this.isShuttingDown || this.currentBackfillAgent === agentName || this.backfillQueue.includes(agentName)) {
-      return;
-    }
-    this.backfillQueue.push(agentName);
+    if (this.isShuttingDown || !this.backfills.enqueue(agentName)) return;
     this.publishBackfillStatus();
     this.pumpBackfillQueue();
   }
   pumpBackfillQueue() {
-    if (this.isShuttingDown || this.currentBackfillAgent) return;
-    const agentName = this.backfillQueue.shift();
-    if (!agentName) return;
-    this.currentBackfillAgent = agentName;
-    this.currentBackfillProgress = void 0;
+    if (this.isShuttingDown) return;
+    const attempt = this.backfills.startNext();
+    if (!attempt) return;
     this.publishBackfillStatus();
-    void this.runBackfill(agentName).then((result) => {
-      if (this.isShuttingDown) return;
-      this.currentBackfillAgent = void 0;
-      this.currentBackfillProgress = void 0;
-      if (result === "committed") {
-        if (!this.completedBackfillAgents.includes(agentName)) {
-          this.completedBackfillAgents.push(agentName);
+    void this.runBackfill(attempt).then((result) => this.completeBackfillAttempt(attempt, result)).catch((error) => this.rejectBackfillAttempt(attempt, error));
+  }
+  completeBackfillAttempt(attempt, result) {
+    if (this.isShuttingDown) return;
+    const current = this.backfills.stateFor(attempt.agentName);
+    if (current?.status === "running" && current.attemptId === attempt.attemptId) {
+      this.flushProgressStatus(`backfill:${attempt.agentName}`);
+      if (this.backfills.complete(attempt, result)) {
+        if (result === "failed") {
+          this.cacheIntegrityValidUntilByAgent.delete(attempt.agentName);
+        } else if (result === "committed") {
+          this.cacheIntegrityValidUntilByAgent.set(
+            attempt.agentName,
+            Date.now() + BACKFILL_INTERVAL_MS
+          );
         }
-        this.failedBackfillAgents = this.failedBackfillAgents.filter(
-          (failedAgent) => failedAgent !== agentName
-        );
-      } else if (!this.failedBackfillAgents.includes(agentName)) {
-        this.failedBackfillAgents.push(agentName);
-        this.cacheIntegrityCheckedAgents.delete(agentName);
+        this.publishBackfillStatus();
       }
-      this.publishBackfillStatus();
-      this.pumpBackfillQueue();
-    });
+    }
+    this.pumpBackfillQueue();
   }
-  runBackfill(agentName) {
-    return this.scheduler.run(agentName, "backfill", () => this.performBackfill(agentName));
+  rejectBackfillAttempt(attempt, error) {
+    appLogger.error("scan.backfill.queue_error", { agent: attempt.agentName, error });
+    this.completeBackfillAttempt(attempt, "failed");
   }
-  async performBackfill(agentName) {
+  runBackfill(attempt) {
+    return this.scheduler.run(attempt.agentName, "backfill", () => this.performBackfill(attempt));
+  }
+  async performBackfill(attempt) {
+    const { agentName } = attempt;
     const startedAt = performance.now();
     const agent = this.findAgent(agentName);
     if (!agent || !agent.isAvailable()) return "skipped";
@@ -2414,25 +3691,42 @@ var AgentSyncEngine = class {
     const meta = cached?.meta ?? buildAgentCacheMeta(agent);
     const backfillCursor = getAgentFullSyncCursor(agentName);
     if (cached) restoreAgentCacheMeta(agent, cached);
+    let durableCommitted = false;
     try {
       markAgentFullSyncStarted(agentName);
+      const operation = agent instanceof FileSystemSessionSource ? { kind: "source-backfill", cursor: backfillCursor, checkpoint: "durable" } : { kind: "full-backfill", cursor: backfillCursor, checkpoint: "durable" };
+      appLogger.info("scan.backfill.started", {
+        agent: agentName,
+        cursor: backfillCursor ?? void 0,
+        durable_checkpoints: operation.checkpoint === "durable"
+      });
       const result = await this.runWorker(
         agent,
         baseline,
-        null,
+        operation,
         {},
         {
-          sourceSync: agent instanceof FileSystemSessionSource,
-          backfill: true,
-          backfillCursor,
+          backfillAttempt: attempt,
           meta,
-          checkpoint: true
+          onCheckpoint: (checkpoint) => this.handleBackfillCheckpoint(agentName, checkpoint)
         }
       );
       agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
       const fullSessions = attachMissingProjectIdentities(result.sessions);
-      this.currentBackfillProgress = { phase: "indexing", sessions: fullSessions.length };
-      this.publishBackfillStatus();
+      this.flushProgressStatus(`backfill:${agentName}`);
+      const updatePublicationPhase = (phase) => {
+        if (this.backfills.updateProgress(attempt, {
+          phase,
+          sessions: fullSessions.length
+        })) {
+          this.publishProgressStatus(
+            `backfill:${agentName}`,
+            phase,
+            this.scanStatus.updateBackfill(this.backfills.status())
+          );
+        }
+      };
+      updatePublicationPhase("publish-queued");
       await this.commitSessionPublication({
         context: "scan.backfill",
         agentName,
@@ -2444,9 +3738,15 @@ var AgentSyncEngine = class {
           agentName,
           sessions: fullSessions,
           meta: buildAgentCacheMeta(agent),
+          completeness: result.completeness,
+          removedSessionIds: result.explicitRemovedSessionIds,
           saveCache: true
-        }
+        },
+        onPublishing: () => updatePublicationPhase("publishing")
       });
+      durableCommitted = true;
+      this.options.workerRunner.commit?.(agentName);
+      if (result.sourceFailures?.length) throw sourceFailureError(result.sourceFailures);
       markAgentFullSyncCompleted(agentName);
       appLogger.info("scan.backfill.done", {
         agent: agentName,
@@ -2456,38 +3756,39 @@ var AgentSyncEngine = class {
       });
       return "committed";
     } catch (error) {
+      if (!durableCommitted) agent.setSessionMetaMap(new Map(Object.entries(meta)));
+      this.options.workerRunner.discard?.(agentName);
       appLogger.error("scan.backfill.error", { agent: agentName, error });
       console.error(`[${agentName}] Backfill failed:`, error);
       return "failed";
     }
   }
-  backfillStatus() {
-    return {
-      active: this.currentBackfillAgent != null || this.backfillQueue.length > 0,
-      pendingAgents: [...this.backfillQueue],
-      currentAgent: this.currentBackfillAgent,
-      progress: this.currentBackfillProgress,
-      completedAgents: [...this.completedBackfillAgents],
-      failedAgents: [...this.failedBackfillAgents]
-    };
-  }
   buildFullSearchIndexJobs(context) {
     const snapshot = this.sessionIndex.snapshot();
-    return snapshot.agents.map((agent) => {
+    return snapshot.agents.flatMap((agent) => {
+      if (!(agent.name in snapshot.byAgent)) return [];
       const cached = loadCachedSessions(agent.name);
-      return cached ? {
-        kind: "full",
-        context,
-        agentName: agent.name,
-        sessions: cached.sessions,
-        meta: cached.meta
-      } : {
-        kind: "full",
-        context,
-        agentName: agent.name,
-        sessions: snapshot.byAgent[agent.name] ?? [],
-        meta: buildAgentCacheMeta(agent)
-      };
+      return [
+        cached ? {
+          kind: "full",
+          context,
+          agentName: agent.name,
+          sessions: cached.sessions,
+          meta: cached.meta,
+          completeness: "partial",
+          removedSessionIds: [],
+          searchIndexOptions: { includePendingReindex: false }
+        } : {
+          kind: "full",
+          context,
+          agentName: agent.name,
+          sessions: snapshot.byAgent[agent.name] ?? [],
+          meta: buildAgentCacheMeta(agent),
+          completeness: "partial",
+          removedSessionIds: [],
+          searchIndexOptions: { includePendingReindex: false }
+        }
+      ];
     });
   }
   publicationId(context, agentName) {
@@ -2503,7 +3804,11 @@ var AgentSyncEngine = class {
       jobs: jobs.length
     });
     try {
-      await this.searchIndexJobs.enqueue(context, jobs);
+      const publicationJobs = jobs.map((job) => ({
+        ...job,
+        publicationId: details.publicationId
+      }));
+      await (details.onStarted ? this.searchIndexJobs.enqueue(context, publicationJobs, details.onStarted) : this.searchIndexJobs.enqueue(context, publicationJobs));
     } catch (error) {
       appLogger.error("session.publication.failed", {
         publication_id: details.publicationId,
@@ -2524,7 +3829,8 @@ var AgentSyncEngine = class {
     const publicationId = this.publicationId(publication.context, publication.agentName);
     await this.commitSearchIndex(publication.context, [publication.indexJob], {
       publicationId,
-      agent: publication.agentName
+      agent: publication.agentName,
+      ...publication.onPublishing ? { onStarted: publication.onPublishing } : {}
     });
     const diffStartedAt = performance.now();
     const event = this.sessionIndex.commitAgentSessions(
@@ -2701,7 +4007,7 @@ var SessionWatcher = class {
       }
     }
     this.stablePaths.clear();
-    await Promise.all(this.watchers.map((watcher) => watcher.close()));
+    await Promise.all(this.watchers.map(({ watcher }) => watcher.close()));
     this.watchers = [];
     this.fallbackWatchScopes.clear();
     this.listeners.clear();
@@ -2724,7 +4030,7 @@ var SessionWatcher = class {
       watcher.on("error", (error) => {
         this.reportWatchError("watch.error", { path, recursive, error });
       });
-      this.watchers.push(watcher);
+      this.watchers.push({ path, recursive, watcher });
       return true;
     } catch (error) {
       if (recursive && isRecursiveWatchUnavailable(error)) {
@@ -2770,7 +4076,20 @@ var SessionWatcher = class {
         this.watchDirectoryTree(path, scopes);
       }
     } catch {
+      this.unwatchFallbackTree(path);
+    }
+  }
+  unwatchFallbackTree(path) {
+    const active = [];
+    for (const registration of this.watchers) {
+      if (registration.recursive || !isSameOrChildPath(path, registration.path)) {
+        active.push(registration);
+        continue;
+      }
+      registration.watcher.close();
+      this.fallbackWatchScopes.delete(registration.path);
     }
+    this.watchers = active;
   }
   handleWatchEvent(watchPath, scopes, eventType, filename) {
     const changedPath = resolveWatchEventPath(watchPath, filename);
@@ -2852,6 +4171,7 @@ var SessionWatcher = class {
 import { Worker as Worker2 } from "worker_threads";
 var SHUTDOWN_ERROR_MESSAGE2 = "Scan refresh worker shut down";
 function applySessionChanges2(previousSessions, changes, removedSessionIds) {
+  if (changes.length === 0 && removedSessionIds.length === 0) return previousSessions;
   const replacedIds = new Set(removedSessionIds);
   for (const { session } of changes) replacedIds.add(session.id);
   const retained = previousSessions.filter((session) => !replacedIds.has(session.id));
@@ -2874,8 +4194,10 @@ function applySessionChanges2(previousSessions, changes, removedSessionIds) {
   return next;
 }
 function applyMetaChanges(previous, changed, replacedSessionIds) {
+  const replacedIds = [...replacedSessionIds];
+  if (Object.keys(changed).length === 0 && replacedIds.length === 0) return previous;
   const next = { ...previous };
-  for (const id of replacedSessionIds) delete next[id];
+  for (const id of replacedIds) delete next[id];
   return Object.assign(next, changed);
 }
 var ThreadWorkerRunner = class {
@@ -2888,23 +4210,27 @@ var ThreadWorkerRunner = class {
   isShuttingDown = false;
   get activeCount() {
     let count = 0;
-    for (const slot of this.workers.values()) count += slot.pending.size;
+    for (const slot of this.workers.values()) {
+      count += slot.pending.size + Number(slot.awaitingCommit != null);
+    }
     return count;
   }
   run(agentName, payload) {
     if (this.isShuttingDown) return Promise.reject(new Error(SHUTDOWN_ERROR_MESSAGE2));
+    const existingSlot = this.workers.get(agentName);
+    if (existingSlot && (existingSlot.pending.size > 0 || existingSlot.awaitingCommit)) {
+      return Promise.reject(new Error(`Scan refresh worker for ${agentName} is busy`));
+    }
+    const generation = existingSlot?.generation ?? 0;
     const request = {
       type: "run",
       requestId: this.nextRequestId++,
       agentName,
-      previousSessions: payload.previousSessions,
-      changedIds: payload.changedIds,
-      sourceSync: payload.sourceSync,
-      backfill: payload.backfill,
-      backfillCursor: payload.backfillCursor,
-      checkpoint: payload.checkpoint,
+      generation,
+      pricingGenerationId: getPricingGeneration().id,
+      operation: payload.operation,
       scanOptions: payload.scanOptions,
-      meta: payload.meta
+      ...existingSlot ? {} : { previousSessions: payload.previousSessions, meta: payload.meta }
     };
     return new Promise((resolve4, reject) => {
       let slot = this.workers.get(agentName);
@@ -2913,7 +4239,7 @@ var ThreadWorkerRunner = class {
         try {
           slot = this.createWorker(agentName, request);
         } catch (error) {
-          reject(error instanceof Error ? error : new Error(String(error)));
+          reject(toError(error));
           return;
         }
       }
@@ -2921,6 +4247,7 @@ var ThreadWorkerRunner = class {
         resolve: resolve4,
         reject,
         payload,
+        generation,
         onProgress: payload.onProgress,
         onCheckpoint: payload.onCheckpoint
       });
@@ -2929,11 +4256,33 @@ var ThreadWorkerRunner = class {
           slot.worker.postMessage(request);
         } catch (error) {
           slot.pending.delete(request.requestId);
-          reject(error instanceof Error ? error : new Error(String(error)));
+          reject(toError(error));
+          this.invalidateWorker(agentName, slot);
         }
       }
     });
   }
+  commit(agentName) {
+    const slot = this.workers.get(agentName);
+    const awaiting = slot?.awaitingCommit;
+    if (!slot || !awaiting) return;
+    const request = {
+      type: "commit",
+      requestId: awaiting.requestId,
+      generation: awaiting.generation
+    };
+    try {
+      slot.worker.postMessage(request);
+      slot.awaitingCommit = null;
+      slot.generation += 1;
+    } catch {
+      this.invalidateWorker(agentName, slot);
+    }
+  }
+  discard(agentName) {
+    const slot = this.workers.get(agentName);
+    if (slot) this.invalidateWorker(agentName, slot);
+  }
   async shutdown() {
     this.isShuttingDown = true;
     const slots = [...this.workers.values()];
@@ -2948,14 +4297,22 @@ var ThreadWorkerRunner = class {
   }
   createWorker(agentName, request) {
     const worker = new Worker2(this.workerUrl, { workerData: request });
-    const slot = { worker, pending: /* @__PURE__ */ new Map(), closed: false };
+    const slot = {
+      agentName,
+      worker,
+      pending: /* @__PURE__ */ new Map(),
+      generation: request.generation,
+      awaitingCommit: null,
+      closed: false
+    };
     worker.unref();
     this.workers.set(agentName, slot);
     worker.on("message", (message) => {
+      if (appLogger.consumeWorkerMessage(message)) return;
       this.handleMessage(slot, message);
     });
     worker.on("error", (error) => {
-      this.closeWorker(agentName, slot, error);
+      this.closeWorker(agentName, slot, toError(error));
     });
     worker.on("exit", (code) => {
       if (slot.closed) return;
@@ -2970,34 +4327,59 @@ var ThreadWorkerRunner = class {
   handleMessage(slot, message) {
     const pending = slot.pending.get(message.requestId);
     if (!pending) return;
+    if (message.generation !== pending.generation) {
+      const error = new Error(
+        `Scan refresh generation mismatch: expected ${pending.generation}, received ${message.generation}`
+      );
+      slot.pending.delete(message.requestId);
+      pending.reject(error);
+      this.invalidateWorker(slot.agentName, slot);
+      return;
+    }
     if (message.type === "progress") {
       pending.onProgress?.(message.progress);
       return;
     }
     if (message.type === "checkpoint") {
-      pending.onCheckpoint?.(message.checkpoint);
+      try {
+        pending.onCheckpoint?.(message.checkpoint);
+      } catch (error) {
+        slot.pending.delete(message.requestId);
+        pending.reject(toError(error));
+        this.invalidateWorker(slot.agentName, slot);
+      }
       return;
     }
     slot.pending.delete(message.requestId);
     if (message.type === "error") {
       pending.reject(new Error(message.error));
+      this.invalidateWorker(slot.agentName, slot);
       return;
     }
     const changedIds = message.changes.map(({ session }) => session.id);
     const replacedSessionIds = [...changedIds, ...message.removedSessionIds];
     const removedMetaIds = [...message.removedSessionIds, ...message.removedMetaIds];
     try {
-      pending.resolve({
+      const result = {
         sessions: applySessionChanges2(
           pending.payload.previousSessions,
           message.changes,
           message.removedSessionIds
         ),
         meta: applyMetaChanges(pending.payload.meta, message.meta, removedMetaIds),
-        changedIds: pending.payload.sourceSync ? replacedSessionIds : void 0
-      });
+        changedIds: replacedSessionIds,
+        sourceFailures: message.sourceFailures,
+        completeness: message.completeness,
+        explicitRemovedSessionIds: message.explicitRemovedSessionIds
+      };
+      slot.awaitingCommit = {
+        requestId: message.requestId,
+        generation: message.generation
+      };
+      pending.resolve(result);
     } catch (error) {
-      pending.reject(error instanceof Error ? error : new Error(String(error)));
+      pending.reject(toError(error));
+      this.invalidateWorker(slot.agentName, slot);
     }
   }
   closeWorker(agentName, slot, error) {
@@ -3006,6 +4388,15 @@ var ThreadWorkerRunner = class {
     if (this.workers.get(agentName) === slot) this.workers.delete(agentName);
     for (const pending of slot.pending.values()) pending.reject(error);
     slot.pending.clear();
+    slot.awaitingCommit = null;
+  }
+  invalidateWorker(agentName, slot) {
+    this.closeWorker(
+      agentName,
+      slot,
+      new Error(`Scan refresh worker state discarded for ${agentName}`)
+    );
+    void slot.worker.terminate().catch(() => void 0);
   }
 };
 
@@ -3128,6 +4519,7 @@ var LiveScanStore = class {
       await this.watcher.dispose();
       this.watcher = null;
     }
+    closeCacheStorage();
   }
   emit(event) {
     if (this.shuttingDown) return;
@@ -3192,6 +4584,12 @@ function printScanResults(agents) {
 }
 
 // src/session-index-output.ts
+function formatScanFailureDiagnostics(snapshot) {
+  return Object.values(snapshot.scanFailures ?? {}).map((failure) => {
+    const source = failure.sourcePath ? ` at ${failure.sourcePath}` : "";
+    return `[${failure.agentName}] Scan failed during ${failure.stage}${source} (${failure.errorClass}): ${failure.message}`;
+  });
+}
 function buildSessionIndexOutput(snapshot, window = {}) {
   const sessions = filterSessionTreeByActivityWindow(snapshot.sessions, window.from, window.to);
   const agents = getAgentInfoMap(
@@ -3387,12 +4785,6 @@ var main = defineCommand({
     const clearCache = args["clear-cache"];
     const hostname = args.host;
     const remoteAccess = args["remote-access"];
-    if (!isLoopbackHostname(hostname) && !remoteAccess) {
-      console.error(
-        `Refusing to expose CodeSesh on ${hostname} without authentication. Add --remote-access to continue.`
-      );
-      process.exit(1);
-    }
     let transport;
     try {
       transport = resolveRemoteTransport({
@@ -3405,6 +4797,12 @@ var main = defineCommand({
       console.error(error instanceof Error ? error.message : String(error));
       process.exit(1);
     }
+    if (resolveRemoteAccessPolicy(hostname, transport).authenticationRequired && !remoteAccess) {
+      console.error(
+        `Refusing to expose CodeSesh on ${hostname} without authentication. Add --remote-access to continue.`
+      );
+      process.exit(1);
+    }
     if (trace) {
       perf.enable();
     }
@@ -3418,7 +4816,7 @@ var main = defineCommand({
       log_path: appLogger.getLogPath()
     });
     if (clearCache) {
-      const { clearCache: clear } = await import("./dist-ALXOBKV2.js");
+      const { clearCache: clear } = await import("./dist-N2PQATP2.js");
       clear();
       appLogger.info("cache.clear");
       console.log("Cache cleared.");
@@ -3468,6 +4866,13 @@ var main = defineCommand({
     }
     if (jsonOnly) {
       await pricingRefresh.cancel();
+      const scanFailureDiagnostics = formatScanFailureDiagnostics(result);
+      if (scanFailureDiagnostics.length > 0) {
+        await store.shutdown();
+        for (const diagnostic of scanFailureDiagnostics) console.error(diagnostic);
+        process.exitCode = 1;
+        return;
+      }
       const output = buildSessionIndexOutput(result, { from: listDefaultFrom, to: listDefaultTo });
       appLogger.info("cli.json_output", {
         sessions: output.sessions.length,