codesesh 1.0.3 → 1.0.4

package/dist/index.js

@@ -1,79 +1,94 @@
 #!/usr/bin/env node
+import {
+  attachProjectMetricsFromTree,
+  buildDashboard,
+  getSessionActivityTime,
+  summarizeProjects
+} from "./chunk-MBZ4VV4C.js";
 import {
   AGENT_UNAVAILABLE_DURING_SCAN_ERROR_CODE,
   AgentUnavailableDuringScanError
 } from "./chunk-RF3EEWPH.js";
+import "./chunk-QH2HOXJH.js";
 import {
   appLogger,
   logSearchIndexSync
-} from "./chunk-WAKW5OPS.js";
+} from "./chunk-G4HRD3AR.js";
 import {
-  FileSystemSessionSource,
-  PROJECT_IDENTITY_RESOLVER_REVISION,
-  SessionAliasValidationError,
-  StateStorageUnavailableError,
-  addCalendarDays,
   attachMissingProjectIdentities,
-  attachProjectMetricsFromTree,
   buildAgentCacheMeta,
-  buildDashboard,
-  buildSessionTree,
+  buildSessionPersistenceDiff,
   closeCacheStorage,
+  commitAgentRefreshCheck,
   computeSessionDiff,
-  countCalendarDays,
-  createProjectScopeMatcherFromIdentity,
-  createRegisteredAgents,
-  createSessionIndex,
-  createSessionProjectionContext,
-  deleteBookmark,
-  deleteSessionAlias,
-  executeSessionSearch,
-  filterSessionSearchCandidates,
-  filterSessionTreeByActivityWindow,
-  formatSessionReference,
+  filterIndexedSessionReferences,
   getAgentFullSyncCursor,
-  getAgentInfoMap,
   getAnalyticsRevision,
-  getPricingGeneration,
   getSearchProjectDirectory,
-  getSessionActivityTime,
-  getSessionAgentKey,
-  importBookmarks,
-  isProjectIdentityKind,
-  listBookmarks,
   listCachedProjectGroups,
   listDashboardCostFacts,
   listFileActivity,
-  listSessionAliases,
   loadCachedSessionHeads,
-  loadCachedSessions,
   markAgentFullSyncCompleted,
   markAgentFullSyncProgress,
   markAgentFullSyncStarted,
-  matchesProjectIdentity,
-  matchesProjectScope,
-  materializeBookmarkViews,
   materializeSessionDetailResponse,
   mergeSearchQueryOptions,
+  readAgentCacheInitialization,
+  readAgentLastFullSyncAt,
+  readCachedSessions,
+  readPendingSearchIndexMaintenance,
+  resolveSessionSnapshotCompleteness,
+  scanSessions,
+  searchFileActivitySessions,
+  searchSessions,
+  selectAgentRefresh,
+  sessionMatchesSearchCost,
+  sessionSignature,
+  sortSessions
+} from "./chunk-BYB77UAJ.js";
+import {
+  PROJECT_IDENTITY_RESOLVER_REVISION,
+  createProjectScopeMatcherFromIdentity,
+  matchesProjectScope,
+  normalizeProjectDirectory
+} from "./chunk-3SXCTDD6.js";
+import {
+  createRegisteredAgents,
+  getAgentInfoMap
+} from "./chunk-YCUN52HA.js";
+import {
+  addCalendarDays,
+  assertIdentifiedSessionHead,
+  assertSessionIdentity,
+  buildSessionTree,
+  columnExists,
+  countCalendarDays,
+  createSessionIndex,
+  createSessionProjectionContext,
+  filterSessionTreeByActivityWindow,
+  formatSessionReference,
+  getPricingGeneration,
+  getSessionReferenceKey,
+  getUserVersion,
+  isProjectIdentityKind,
+  isSmartTag,
+  matchesProjectIdentity,
   mergeSessionsUpdatedEvents,
   mergeSortedSessions,
-  normalizeProjectDirectory,
   normalizeSessionReference,
+  openDb,
   perf,
   publishPendingPricing,
-  readAgentCacheInitialization,
-  readAgentLastFullSyncAt,
-  readCachedSessions,
-  readPendingSearchIndexMaintenance,
   refreshPricingCache,
-  scanSessions,
+  runSchemaMigrations,
   sessionRoutePath,
-  sessionSignature,
-  sortSessions,
+  setUserVersion,
   startOfCalendarDay,
-  upsertBookmark,
-  upsertSessionAlias
-} from "./chunk-PSHZZITB.js";
+  tableExists,
+  toPublicReferencedSessionHead,
+  toPublicSessionHead
+} from "./chunk-W4PZHL2C.js";
 
 // src/index.ts
 import { defineCommand, runMain } from "citty";
@@ -93,6 +108,422 @@ import { fileURLToPath } from "url";
 // src/api/routes.ts
 import { Hono } from "hono";
 
+// ../core/dist/runtime/search.mjs
+function executeSessionSearch(query, options, snapshot, context = {}) {
+  const merged = mergeSearchQueryOptions(query, options);
+  if (!needsIndexedSearch(merged.text, merged.options)) {
+    return searchRecentSessions(snapshot, merged.options, context);
+  }
+  return searchIndexedSessions(query, merged.text, merged.parsed, merged.options);
+}
+function needsIndexedSearch(textQuery, options) {
+  return Boolean(textQuery || options.file || options.fileKind || options.tools?.length);
+}
+function matchesRecentSearchFilters(session, options, projectScope, inclusiveCost) {
+  if (options.projectKind || options.projectKey) {
+    if (!options.projectKind || !options.projectKey || !matchesProjectIdentity(session.project_identity, {
+      kind: options.projectKind,
+      key: options.projectKey
+    })) {
+      return false;
+    }
+  }
+  if (projectScope && !matchesProjectScope(session, projectScope)) return false;
+  if (options.project) {
+    const projectNeedle = options.project.toLowerCase();
+    const projectText = [
+      session.project_identity?.key,
+      session.project_identity?.displayName,
+      session.directory
+    ].filter(Boolean).join("\n").toLowerCase();
+    if (!projectText.includes(projectNeedle)) return false;
+  }
+  if (options.tags?.length && !options.tags.every((tag) => session.smart_tags?.includes(tag))) {
+    return false;
+  }
+  if (!sessionMatchesSearchCost(session, options, inclusiveCost)) return false;
+  return true;
+}
+function matchesSessionSearchFilters(agentName, session, options, projectScope = null, inclusiveCost = session.stats.total_cost) {
+  if (options.agent && agentName !== options.agent) return false;
+  const activity = getSessionActivityTime(session);
+  if (options.from != null && activity < options.from) return false;
+  if (options.to != null && activity > options.to) return false;
+  return matchesRecentSearchFilters(session, options, projectScope, inclusiveCost);
+}
+function filterSessionSearchCandidates(candidates, options, context = {}) {
+  const projectScope = options.projectScope ?? null;
+  const sessionSnapshot = context.sessionSnapshot ?? candidates.map((candidate) => candidate.session);
+  const inclusiveCosts = buildInclusiveCostLookup(sessionSnapshot, options, context.sessionTree);
+  const headMatches = candidates.filter(
+    (candidate) => matchesSessionSearchFilters(
+      candidate.reference.agentName,
+      candidate.session,
+      options,
+      projectScope,
+      inclusiveCostFor(candidate.reference.agentName, candidate.session, inclusiveCosts)
+    )
+  );
+  if (!options.file && !options.fileKind && !options.tools?.length) return headMatches;
+  const indexedMatches = filterIndexedSessionReferences(
+    headMatches.map((candidate) => ({
+      agentName: candidate.reference.agentName,
+      sessionId: candidate.reference.sessionId
+    })),
+    {
+      file: options.file,
+      fileKind: options.fileKind,
+      tools: options.tools
+    }
+  );
+  return headMatches.filter(
+    (candidate) => indexedMatches.has(getSessionReferenceKey(candidate.reference))
+  );
+}
+function searchRecentSessions(snapshot, options, context) {
+  const limit = Math.max(0, Math.trunc(options.limit ?? 50));
+  if (limit === 0) return [];
+  const projectScope = options.projectScope ?? null;
+  const inclusiveCosts = buildInclusiveCostLookup(snapshot.sessions, options, context.sessionTree);
+  const sessions = options.agent ? snapshot.byAgent[options.agent] ?? [] : snapshot.sessions;
+  const results = [];
+  for (const session of sessions) {
+    const agentName = options.agent ?? session.reference.agentName;
+    if (!matchesSessionSearchFilters(
+      agentName,
+      session,
+      options,
+      projectScope,
+      inclusiveCostFor(agentName, session, inclusiveCosts)
+    )) {
+      continue;
+    }
+    results.push({
+      reference: session.reference,
+      session,
+      snippet: `Recent session \xB7 ${session.directory}`,
+      snippetHighlights: [],
+      matchType: "recent"
+    });
+    if (results.length >= limit) break;
+  }
+  return results;
+}
+function buildInclusiveCostLookup(sessions, options, sessionTree) {
+  if (options.costMin == null && options.costMax == null) return null;
+  return (sessionTree ?? buildSessionTree(sessions)).byRouteKey;
+}
+function inclusiveCostFor(agentName, session, lookup) {
+  return lookup?.get(getSessionReferenceKey({ agentName, sessionId: session.reference.sessionId }))?.inclusiveStats.cost ?? session.stats.total_cost;
+}
+function deriveFileQuery(query, parsed, options) {
+  return options.file ?? (!parsed.text ? parsed.filters.file : void 0) ?? (!parsed.hasQualifiers && query ? parsed.text || query : "");
+}
+function mergeSearchResultSources(results, limit) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const result of results) {
+    const key = getSessionReferenceKey(result.reference);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(result);
+    if (merged.length >= limit) break;
+  }
+  return merged;
+}
+function canSkipSessionsSearch(fileQuery, textQuery) {
+  return Boolean(fileQuery && !textQuery);
+}
+function searchIndexedSessions(query, textQuery, parsed, options) {
+  const fileQuery = deriveFileQuery(query, parsed, options);
+  const fileResults = fileQuery ? searchFileActivitySessions(fileQuery, options) : [];
+  const sessionResults = canSkipSessionsSearch(fileQuery, textQuery) ? [] : searchSessions(query, options);
+  const textMatchReferences = textQuery && options.file ? new Set(sessionResults.map((result) => getSessionReferenceKey(result.reference))) : null;
+  const matchingFileResults = textMatchReferences ? fileResults.filter(
+    (result) => textMatchReferences.has(getSessionReferenceKey(result.reference))
+  ) : fileResults;
+  return mergeSearchResultSources([...matchingFileResults, ...sessionResults], options.limit ?? 50);
+}
+
+// src/project-identity-resolver.ts
+import { Worker } from "worker_threads";
+var PROJECT_IDENTITY_RESOLVER_MAX_WORKERS = 2;
+var PROJECT_IDENTITY_RESOLVER_MAX_QUEUED_REQUESTS = 8;
+var PROJECT_IDENTITY_RESOLVER_TIMEOUT_MS = 2e3;
+var SHUTDOWN_ERROR_MESSAGE = "Project identity resolver shut down";
+var ProjectIdentityQueueFullError = class extends Error {
+  constructor() {
+    super("Project identity resolver queue is full");
+    this.name = "ProjectIdentityQueueFullError";
+  }
+};
+var ProjectIdentityTimeoutError = class extends Error {
+  constructor() {
+    super("Project identity resolution timed out");
+    this.name = "ProjectIdentityTimeoutError";
+  }
+};
+var ProjectIdentityRequestAbortedError = class extends Error {
+  constructor() {
+    super("Project identity resolution was aborted");
+    this.name = "ProjectIdentityRequestAbortedError";
+  }
+};
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function requireSafeInteger(value, minimum, name) {
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new RangeError(`${name} must be a safe integer greater than or equal to ${minimum}`);
+  }
+  return value;
+}
+function isWorkerMessage(message) {
+  return typeof message === "object" && message !== null && "type" in message && (message.type === "resolved" && "requestId" in message && "projection" in message || message.type === "failed" && "requestId" in message && "error" in message);
+}
+var ThreadProjectIdentityResolver = class {
+  constructor(workerUrl, options = {}) {
+    this.workerUrl = workerUrl;
+    this.maxWorkers = requireSafeInteger(
+      options.maxWorkers ?? PROJECT_IDENTITY_RESOLVER_MAX_WORKERS,
+      1,
+      "maxWorkers"
+    );
+    const maxQueuedRequests = requireSafeInteger(
+      options.maxQueuedRequests ?? PROJECT_IDENTITY_RESOLVER_MAX_QUEUED_REQUESTS,
+      0,
+      "maxQueuedRequests"
+    );
+    this.timeoutMs = requireSafeInteger(
+      options.timeoutMs ?? PROJECT_IDENTITY_RESOLVER_TIMEOUT_MS,
+      1,
+      "timeoutMs"
+    );
+    this.maxOutstandingRequests = requireSafeInteger(
+      this.maxWorkers + maxQueuedRequests,
+      this.maxWorkers,
+      "request capacity"
+    );
+  }
+  workerUrl;
+  workers = /* @__PURE__ */ new Set();
+  queue = [];
+  requestsByDirectory = /* @__PURE__ */ new Map();
+  maxWorkers;
+  maxOutstandingRequests;
+  timeoutMs;
+  nextRequestId = 1;
+  isShuttingDown = false;
+  resolve(cwd, signal) {
+    if (this.isShuttingDown) return Promise.reject(new Error(SHUTDOWN_ERROR_MESSAGE));
+    if (signal?.aborted) return Promise.reject(new ProjectIdentityRequestAbortedError());
+    const normalizedCwd = normalizeProjectDirectory(cwd);
+    let request = this.requestsByDirectory.get(normalizedCwd);
+    if (!request) {
+      if (this.requestsByDirectory.size >= this.maxOutstandingRequests) {
+        appLogger.warn("project_identity.queue.full", {
+          active_workers: this.activeWorkerCount(),
+          queued_requests: this.queue.length,
+          request_capacity: this.maxOutstandingRequests
+        });
+        return Promise.reject(new ProjectIdentityQueueFullError());
+      }
+      request = {
+        requestId: this.nextRequestId++,
+        cwd: normalizedCwd,
+        subscribers: /* @__PURE__ */ new Set(),
+        timeout: null
+      };
+      this.requestsByDirectory.set(normalizedCwd, request);
+      this.queue.push(request);
+    }
+    const resolution = this.subscribe(request, signal);
+    this.pump();
+    return resolution;
+  }
+  async shutdown() {
+    if (this.isShuttingDown) return;
+    this.isShuttingDown = true;
+    const error = new Error(SHUTDOWN_ERROR_MESSAGE);
+    while (this.queue.length > 0) this.rejectRequest(this.queue[0], error);
+    const retirements = [...this.workers].map((slot) => this.retireWorker(slot, error));
+    await Promise.allSettled(retirements);
+    this.workers.clear();
+  }
+  subscribe(request, signal) {
+    return new Promise((resolve4, reject) => {
+      const subscriber = { resolve: resolve4, reject, signal };
+      request.subscribers.add(subscriber);
+      if (!signal) return;
+      subscriber.abortHandler = () => this.abortSubscriber(request, subscriber);
+      signal.addEventListener("abort", subscriber.abortHandler, { once: true });
+    });
+  }
+  abortSubscriber(request, subscriber) {
+    if (!request.subscribers.delete(subscriber)) return;
+    this.removeAbortHandler(subscriber);
+    subscriber.reject(new ProjectIdentityRequestAbortedError());
+    if (request.subscribers.size > 0) return;
+    const slot = this.workerForRequest(request);
+    if (slot) slot.pending = null;
+    this.releaseRequest(request);
+    if (slot) void this.retireWorker(slot);
+    else this.pump();
+  }
+  pump() {
+    while (!this.isShuttingDown && this.queue.length > 0) {
+      const slot = this.idleWorker() ?? this.createWorker();
+      if (!slot) return;
+      const request = this.queue.shift();
+      if (!request) return;
+      slot.pending = request;
+      request.timeout = setTimeout(() => {
+        if (slot.pending !== request || slot.closed) return;
+        appLogger.warn("project_identity.request.timeout", {
+          request_id: request.requestId,
+          timeout_ms: this.timeoutMs
+        });
+        void this.retireWorker(slot, new ProjectIdentityTimeoutError());
+      }, this.timeoutMs);
+      request.timeout.unref();
+      try {
+        slot.worker.postMessage({
+          type: "resolve",
+          requestId: request.requestId,
+          cwd: request.cwd
+        });
+      } catch (error) {
+        void this.retireWorker(slot, toError(error));
+      }
+    }
+  }
+  idleWorker() {
+    for (const slot of this.workers) {
+      if (!slot.closed && slot.pending == null) return slot;
+    }
+    return null;
+  }
+  activeWorkerCount() {
+    let count = 0;
+    for (const slot of this.workers) {
+      if (!slot.closed && slot.pending != null) count += 1;
+    }
+    return count;
+  }
+  createWorker() {
+    if (this.workers.size >= this.maxWorkers) return null;
+    let worker;
+    try {
+      worker = new Worker(this.workerUrl);
+    } catch (error) {
+      this.rejectQueued(toError(error));
+      return null;
+    }
+    const slot = {
+      worker,
+      pending: null,
+      closed: false,
+      retirement: null
+    };
+    this.workers.add(slot);
+    worker.on("message", (message) => {
+      if (appLogger.consumeWorkerMessage(message)) return;
+      this.handleWorkerMessage(slot, message);
+    });
+    worker.on("error", (error) => {
+      void this.retireWorker(slot, toError(error));
+    });
+    worker.on("exit", (code) => {
+      if (!slot.closed) {
+        this.closeExitedWorker(slot, new Error(`Project identity worker exited with code ${code}`));
+      }
+    });
+    return slot;
+  }
+  handleWorkerMessage(slot, message) {
+    if (!isWorkerMessage(message) || slot.closed) return;
+    const request = slot.pending;
+    if (!request || message.requestId !== request.requestId) return;
+    slot.pending = null;
+    if (message.type === "resolved") this.resolveRequest(request, message.projection);
+    else this.rejectRequest(request, new Error(message.error));
+    this.pump();
+  }
+  closeExitedWorker(slot, error) {
+    slot.closed = true;
+    this.workers.delete(slot);
+    const request = slot.pending;
+    slot.pending = null;
+    if (request) this.rejectRequest(request, error);
+    if (!this.isShuttingDown) this.pump();
+  }
+  retireWorker(slot, error) {
+    if (slot.retirement) return slot.retirement;
+    slot.closed = true;
+    const request = slot.pending;
+    slot.pending = null;
+    if (request && error) this.rejectRequest(request, error);
+    const retirement = (async () => {
+      try {
+        await slot.worker.terminate();
+      } catch (terminationError) {
+        appLogger.warn("project_identity.worker.termination_failed", {
+          error: toError(terminationError).message
+        });
+      } finally {
+        this.workers.delete(slot);
+        if (!this.isShuttingDown) this.pump();
+      }
+    })();
+    slot.retirement = retirement;
+    return retirement;
+  }
+  workerForRequest(request) {
+    for (const slot of this.workers) {
+      if (slot.pending === request) return slot;
+    }
+    return null;
+  }
+  resolveRequest(request, projection) {
+    this.releaseRequest(request);
+    for (const subscriber of request.subscribers) {
+      this.removeAbortHandler(subscriber);
+      subscriber.resolve(projection);
+    }
+    request.subscribers.clear();
+  }
+  rejectRequest(request, error) {
+    this.releaseRequest(request);
+    for (const subscriber of request.subscribers) {
+      this.removeAbortHandler(subscriber);
+      subscriber.reject(error);
+    }
+    request.subscribers.clear();
+  }
+  releaseRequest(request) {
+    if (request.timeout) clearTimeout(request.timeout);
+    request.timeout = null;
+    if (this.requestsByDirectory.get(request.cwd) === request) {
+      this.requestsByDirectory.delete(request.cwd);
+    }
+    const queueIndex = this.queue.indexOf(request);
+    if (queueIndex >= 0) this.queue.splice(queueIndex, 1);
+  }
+  removeAbortHandler(subscriber) {
+    if (subscriber.signal && subscriber.abortHandler) {
+      subscriber.signal.removeEventListener("abort", subscriber.abortHandler);
+    }
+  }
+  rejectQueued(error) {
+    while (this.queue.length > 0) this.rejectRequest(this.queue[0], error);
+  }
+};
+function createProjectIdentityResolver() {
+  return new ThreadProjectIdentityResolver(
+    new URL("./project-identity-worker.js", import.meta.url)
+  );
+}
+
 // src/time-window-resolution.ts
 var ROLLING_DAY_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_DASHBOARD_DAYS = 30;
@@ -112,22 +543,20 @@ function resolveCliWindow(request) {
 }
 function resolveDashboardWindow(request) {
   const now = request.now ?? Date.now();
-  const defaults = request.defaults ?? {};
-  const to = parseOptionalDate(request.query.to) ?? defaults.to ?? now;
-  const hasQueryDays = Boolean(request.query.days?.trim());
-  const parsedDays = hasQueryDays ? parseDays(request.query.days) : void 0;
-  let days = parsedDays != null && parsedDays > 0 ? parsedDays : defaults.days;
-  const queryFrom = parseOptionalDate(request.query.from);
-  if (queryFrom != null) {
-    days ??= countCalendarDays(queryFrom, to);
-    return { from: queryFrom, to, days };
-  }
-  if (parsedDays === 0 || !hasQueryDays && defaults.days === 0) {
+  const to = request.window.to ?? now;
+  const hasQueryDays = Boolean(request.days?.trim());
+  const parsedDays = hasQueryDays ? parseDays(request.days) : void 0;
+  let days = parsedDays != null && parsedDays > 0 ? parsedDays : request.defaultDays;
+  if (request.window.hasExplicitFrom && request.window.from != null) {
+    days ??= countCalendarDays(request.window.from, to);
+    return { from: request.window.from, to, days };
+  }
+  if (parsedDays === 0 || !hasQueryDays && request.defaultDays === 0) {
     return { to, days: 0 };
   }
-  if (defaults.from != null) {
-    days ??= countCalendarDays(defaults.from, to);
-    return { from: defaults.from, to, days };
+  if (request.window.from != null) {
+    days ??= countCalendarDays(request.window.from, to);
+    return { from: request.window.from, to, days };
   }
   const resolvedDays = days != null && days > 0 ? days : DEFAULT_DASHBOARD_DAYS;
   return {
@@ -142,11 +571,6 @@ function parseRequiredDate(value) {
   if (Number.isNaN(timestamp)) throw new Error(`Invalid date: ${value}`);
   return timestamp;
 }
-function parseOptionalDate(value) {
-  if (value == null) return void 0;
-  const timestamp = new Date(value).getTime();
-  return Number.isNaN(timestamp) ? void 0 : timestamp;
-}
 function parseDays(value) {
   if (value == null) return void 0;
   const days = Number.parseInt(value, 10);
@@ -154,19 +578,9 @@ function parseDays(value) {
 }
 
 // src/api/query-params.ts
-var SMART_TAGS = [
-  "bugfix",
-  "refactoring",
-  "feature-dev",
-  "testing",
-  "docs",
-  "git-ops",
-  "build-deploy",
-  "exploration",
-  "planning"
-];
 var SEARCH_LIMIT_POLICY = { defaultValue: 50, maxValue: 100 };
 var FILE_ACTIVITY_LIMIT_POLICY = { defaultValue: 50, maxValue: 200 };
+var PROJECT_PAGE_LIMIT_POLICY = { defaultValue: 100, maxValue: 250 };
 var SESSION_PAGE_LIMIT_POLICY = { defaultValue: 250, maxValue: 500 };
 function searchParams(c) {
   return new URL(c.req.url ?? "http://localhost/", "http://localhost/").searchParams;
@@ -194,7 +608,12 @@ function parseDateWindow(params, defaults) {
   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 };
+  return {
+    kind: "valid",
+    from: from.value,
+    to: to.value,
+    hasExplicitFrom: from.kind === "valid"
+  };
 }
 function parseNumberParam(value) {
   if (value == null || !value.trim()) return void 0;
@@ -227,7 +646,7 @@ function parseSessionQuery(params, knownAgentNames, limitPolicy) {
   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));
+  const tags = values.map((value) => value.toLowerCase()).filter(isSmartTag);
   return tags.length > 0 ? [...new Set(tags)] : void 0;
 }
 function parseFileActivityKind(value) {
@@ -268,7 +687,7 @@ function filterSessionsByActivityWindow(sessions, from, to) {
   return filterSessionTreeByActivityWindow(sessions, from, to);
 }
 
-// src/api/session-pagination.ts
+// src/api/snapshot-pagination.ts
 import { createHash, randomUUID } from "crypto";
 var identityVersions = /* @__PURE__ */ new WeakMap();
 function identityVersion(identity) {
@@ -302,7 +721,7 @@ function decodeCursor(cursor) {
     return null;
   }
 }
-function paginateSessionSnapshot(items, request) {
+function paginateSnapshot(items, request) {
   const snapshot = identityVersion(request.snapshotIdentity);
   const view = identityVersion(request.viewIdentity);
   const query = queryFingerprint(request.query);
@@ -563,24 +982,412 @@ function mergeAliasSearchResults(rankedResults, aliasResults, limit) {
   ].slice(0, limit);
 }
 
-// src/api/session-aliases-view.ts
-function aliasKey(reference) {
-  return `${reference.agentName.toLowerCase()}\0${reference.sessionId}`;
+// ../core/dist/runtime/state.mjs
+import { homedir, platform } from "os";
+import { join } from "path";
+var STATE_DB_FILENAME = "state.db";
+var STATE_SCHEMA_VERSION = 3;
+var MEMORY_STATE_STORE = "memory";
+var stateSchemaEnsuredPath = null;
+function getStateSchemaEnsuredPath() {
+  return stateSchemaEnsuredPath;
+}
+function setStateSchemaEnsuredPath(path) {
+  stateSchemaEnsuredPath = path;
+}
+var StateStorageUnavailableError = class extends Error {
+  constructor() {
+    super("SQLite state database is unavailable");
+    this.name = "StateStorageUnavailableError";
+  }
+};
+function getStateDir() {
+  if (process.env.CODESESH_STATE_DIR) return process.env.CODESESH_STATE_DIR;
+  const currentPlatform = platform();
+  if (currentPlatform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "codesesh");
+  }
+  if (currentPlatform === "win32") {
+    const appData = process.env.APPDATA ?? process.env.LOCALAPPDATA;
+    return join(appData ?? join(homedir(), "AppData", "Roaming"), "codesesh");
+  }
+  return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "codesesh");
+}
+function getStateDbPath() {
+  return join(getStateDir(), STATE_DB_FILENAME);
+}
+function useMemoryStateStore() {
+  return process.env.CODESESH_STATE_STORE === MEMORY_STATE_STORE;
+}
+function createBookmarksTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS bookmarks (
+      agent_name TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      bookmarked_at INTEGER NOT NULL,
+      PRIMARY KEY (agent_name, session_id)
+    );
+  `);
+}
+function migrateBookmarkFacts(db) {
+  db.exec("ALTER TABLE bookmarks RENAME TO bookmarks_with_snapshots");
+  createBookmarksTable(db);
+  db.exec(`
+    INSERT INTO bookmarks(agent_name, session_id, bookmarked_at)
+    SELECT agent_name, session_id, bookmarked_at
+    FROM bookmarks_with_snapshots;
+
+    DROP TABLE bookmarks_with_snapshots;
+  `);
+}
+function createSessionAliasesTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS session_aliases (
+      agent_name TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      alias TEXT NOT NULL,
+      updated_at INTEGER NOT NULL,
+      PRIMARY KEY (agent_name, session_id)
+    );
+  `);
+}
+function createStateSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS state_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+  createBookmarksTable(db);
+  createSessionAliasesTable(db);
+}
+function readLegacyStateVersion(db) {
+  if (!tableExists(db, "state_meta") || !columnExists(db, "state_meta", "key") || !columnExists(db, "state_meta", "value")) {
+    return 0;
+  }
+  const row = db.prepare("SELECT value FROM state_meta WHERE key = 'version'").get();
+  return Number(row?.value ?? 0);
+}
+function getCurrentStateSchemaVersion(db) {
+  const userVersion = getUserVersion(db);
+  if (userVersion > 0) return userVersion;
+  const legacyVersion = readLegacyStateVersion(db);
+  if (legacyVersion > 0) return legacyVersion;
+  return tableExists(db, "bookmarks") ? 1 : 0;
+}
+function hasAnyStateSchema(db) {
+  return tableExists(db, "state_meta") || tableExists(db, "bookmarks");
+}
+function setStateSchemaVersion(db) {
+  createStateSchema(db);
+  setUserVersion(db, STATE_SCHEMA_VERSION);
+  db.prepare(
+    `
+      INSERT INTO state_meta(key, value)
+      VALUES ('version', ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `
+  ).run(String(STATE_SCHEMA_VERSION));
+}
+function ensureSchema(db, dbPath) {
+  const currentVersion = getCurrentStateSchemaVersion(db);
+  if (currentVersion > STATE_SCHEMA_VERSION) return;
+  if (currentVersion === 0 && !hasAnyStateSchema(db)) {
+    setStateSchemaVersion(db);
+    return;
+  }
+  runSchemaMigrations(db, {
+    dbPath,
+    currentVersion,
+    targetVersion: STATE_SCHEMA_VERSION,
+    backupLabel: "state-migration",
+    backupTables: ["bookmarks", "session_aliases"],
+    migrations: [
+      { version: 1, migrate: createBookmarksTable },
+      { version: 2, migrate: createSessionAliasesTable },
+      { version: 3, destructive: true, migrate: migrateBookmarkFacts }
+    ]
+  });
+  if (currentVersion < STATE_SCHEMA_VERSION) {
+    setStateSchemaVersion(db);
+  }
 }
-function loadAliasMap() {
+function withStateDb(fn) {
+  const statePath = getStateDbPath();
+  const db = openDb(statePath);
+  if (!db) throw new StateStorageUnavailableError();
   try {
-    return new Map(listSessionAliases().map((alias) => [aliasKey(alias.reference), alias]));
-  } catch (error) {
-    if (!(error instanceof StateStorageUnavailableError)) {
-      appLogger.warn("api.session_aliases.load_failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
+    if (getStateSchemaEnsuredPath() !== statePath) {
+      ensureSchema(db, statePath);
+      setStateSchemaEnsuredPath(statePath);
     }
-    return /* @__PURE__ */ new Map();
+    return fn(db);
+  } finally {
+    db.close();
   }
 }
-function buildAliasView() {
-  const aliases = loadAliasMap();
+var memoryBookmarks = /* @__PURE__ */ new Map();
+function getBookmarkKey(reference) {
+  const normalized = normalizeSessionReference(reference);
+  return JSON.stringify([normalized.agentName, normalized.sessionId]);
+}
+function compareBookmarks(left, right) {
+  if (left.bookmarkedAt !== right.bookmarkedAt) {
+    return left.bookmarkedAt > right.bookmarkedAt ? -1 : 1;
+  }
+  return getBookmarkKey(left.reference).localeCompare(getBookmarkKey(right.reference));
+}
+function normalizeBookmark(bookmark) {
+  return {
+    reference: normalizeSessionReference(bookmark.reference),
+    bookmarkedAt: bookmark.bookmarkedAt
+  };
+}
+function toBookmarkRecord(row) {
+  return {
+    reference: normalizeSessionReference({
+      agentName: String(row.agent_name ?? ""),
+      sessionId: String(row.session_id ?? "")
+    }),
+    bookmarkedAt: Number(row.bookmarked_at ?? 0)
+  };
+}
+function readBookmarks(db) {
+  const rows = db.prepare(
+    `
+        SELECT agent_name, session_id, bookmarked_at
+        FROM bookmarks
+        ORDER BY bookmarked_at DESC, agent_name ASC, session_id ASC
+      `
+  ).all();
+  return rows.map(toBookmarkRecord);
+}
+function listMemoryBookmarks() {
+  return [...memoryBookmarks.values()].sort(compareBookmarks);
+}
+function listBookmarks() {
+  if (useMemoryStateStore()) return listMemoryBookmarks();
+  return withStateDb(readBookmarks);
+}
+function upsertBookmark(reference) {
+  const normalized = normalizeSessionReference(reference);
+  const key = getBookmarkKey(normalized);
+  if (useMemoryStateStore()) {
+    const bookmark = memoryBookmarks.get(key) ?? {
+      reference: normalized,
+      bookmarkedAt: Date.now()
+    };
+    memoryBookmarks.set(key, bookmark);
+    return bookmark;
+  }
+  return withStateDb((db) => {
+    const row = db.prepare(
+      `
+          INSERT INTO bookmarks(agent_name, session_id, bookmarked_at)
+          VALUES (?, ?, ?)
+          ON CONFLICT(agent_name, session_id) DO UPDATE
+          SET bookmarked_at = bookmarks.bookmarked_at
+          RETURNING agent_name, session_id, bookmarked_at
+        `
+    ).get(normalized.agentName, normalized.sessionId, Date.now());
+    if (!row) {
+      throw new Error("Bookmark upsert returned no row");
+    }
+    return toBookmarkRecord(row);
+  });
+}
+function importBookmarks(bookmarks) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const bookmark of bookmarks) {
+    const normalized = normalizeBookmark(bookmark);
+    const key = getBookmarkKey(normalized.reference);
+    if (!unique.has(key)) unique.set(key, normalized);
+  }
+  if (useMemoryStateStore()) {
+    for (const [key, bookmark] of unique) {
+      if (!memoryBookmarks.has(key)) memoryBookmarks.set(key, bookmark);
+    }
+    return listMemoryBookmarks();
+  }
+  return withStateDb((db) => {
+    const insert = db.prepare(
+      `
+        INSERT INTO bookmarks(agent_name, session_id, bookmarked_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(agent_name, session_id) DO NOTHING
+      `
+    );
+    const write = db.transaction(() => {
+      for (const bookmark of unique.values()) {
+        insert.run(
+          bookmark.reference.agentName,
+          bookmark.reference.sessionId,
+          bookmark.bookmarkedAt
+        );
+      }
+    });
+    write.immediate();
+    return readBookmarks(db);
+  });
+}
+function deleteBookmark(reference) {
+  const normalized = normalizeSessionReference(reference);
+  if (useMemoryStateStore()) {
+    memoryBookmarks.delete(getBookmarkKey(normalized));
+    return;
+  }
+  withStateDb((db) => {
+    db.prepare(
+      `
+        DELETE FROM bookmarks
+        WHERE agent_name = ? AND session_id = ?
+      `
+    ).run(normalized.agentName, normalized.sessionId);
+  });
+}
+var SESSION_ALIAS_MAX_LENGTH = 160;
+var SessionAliasValidationError = class extends Error {
+  constructor() {
+    super("Invalid session alias");
+    this.name = "SessionAliasValidationError";
+  }
+};
+var memoryAliases = /* @__PURE__ */ new Map();
+function getAliasKey(reference) {
+  const normalized = normalizeSessionReference(reference);
+  return JSON.stringify([normalized.agentName, normalized.sessionId]);
+}
+function toSessionAlias(row) {
+  const reference = normalizeSessionReference({
+    agentName: String(row.agent_name ?? ""),
+    sessionId: String(row.session_id ?? "")
+  });
+  return {
+    reference,
+    alias: String(row.alias ?? ""),
+    updatedAt: Number(row.updated_at ?? 0)
+  };
+}
+function normalizeSessionAlias(value) {
+  const alias = value.trim();
+  if (!alias || alias.length > SESSION_ALIAS_MAX_LENGTH) return null;
+  return alias;
+}
+function listSessionAliases() {
+  if (useMemoryStateStore()) return [...memoryAliases.values()];
+  return withStateDb(
+    (db) => db.prepare(
+      `
+          SELECT agent_name, session_id, alias, updated_at
+          FROM session_aliases
+          ORDER BY updated_at DESC
+        `
+    ).all().map(toSessionAlias)
+  );
+}
+function upsertSessionAlias(reference, alias) {
+  const normalizedAlias = normalizeSessionAlias(alias);
+  if (!normalizedAlias) {
+    throw new SessionAliasValidationError();
+  }
+  const normalizedReference = normalizeSessionReference(reference);
+  const saved = {
+    reference: normalizedReference,
+    alias: normalizedAlias,
+    updatedAt: Date.now()
+  };
+  if (useMemoryStateStore()) {
+    memoryAliases.set(getAliasKey(normalizedReference), saved);
+    return saved;
+  }
+  return withStateDb((db) => {
+    db.prepare(
+      `
+        INSERT INTO session_aliases(agent_name, session_id, alias, updated_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(agent_name, session_id) DO UPDATE SET
+          alias = excluded.alias,
+          updated_at = excluded.updated_at
+      `
+    ).run(saved.reference.agentName, saved.reference.sessionId, saved.alias, saved.updatedAt);
+    return saved;
+  });
+}
+function deleteSessionAlias(reference) {
+  const normalizedReference = normalizeSessionReference(reference);
+  if (useMemoryStateStore()) {
+    memoryAliases.delete(getAliasKey(normalizedReference));
+    return;
+  }
+  withStateDb((db) => {
+    db.prepare(
+      `
+        DELETE FROM session_aliases
+        WHERE agent_name = ? AND session_id = ?
+      `
+    ).run(normalizedReference.agentName, normalizedReference.sessionId);
+  });
+}
+function canonicalSession(reference, session) {
+  const normalized = normalizeSessionReference(reference);
+  assertSessionIdentity(session, normalized.agentName);
+  if (session.reference.sessionId !== normalized.sessionId) {
+    throw new Error("Session reference does not match expected session");
+  }
+  return session;
+}
+function compareDescending(left, right) {
+  if (left === right) return 0;
+  return left > right ? -1 : 1;
+}
+function getBookmarkViewTime(bookmark) {
+  return bookmark.availability === "available" ? bookmark.session.time_updated ?? bookmark.session.time_created : bookmark.bookmarkedAt;
+}
+function compareBookmarkViews(left, right) {
+  return compareDescending(getBookmarkViewTime(left), getBookmarkViewTime(right)) || compareDescending(left.bookmarkedAt, right.bookmarkedAt) || getSessionReferenceKey(left.reference).localeCompare(getSessionReferenceKey(right.reference));
+}
+function materializeBookmarkViews(bookmarks, options) {
+  const liveByKey = /* @__PURE__ */ new Map();
+  const missingByKey = /* @__PURE__ */ new Map();
+  const normalizedBookmarks = bookmarks.map((bookmark) => {
+    const reference = normalizeSessionReference(bookmark.reference);
+    return {
+      bookmark: { reference, bookmarkedAt: bookmark.bookmarkedAt },
+      key: getSessionReferenceKey(reference)
+    };
+  });
+  for (const { bookmark, key } of normalizedBookmarks) {
+    const { reference } = bookmark;
+    const live = options.liveSessionsByReference.get(key);
+    if (live) liveByKey.set(key, canonicalSession(reference, live));
+    else if (!missingByKey.has(key)) missingByKey.set(key, reference);
+  }
+  const cachedByKey = /* @__PURE__ */ new Map();
+  if (missingByKey.size > 0 && options.resolveCachedSessions) {
+    for (const cached of options.resolveCachedSessions([...missingByKey.values()])) {
+      const reference = normalizeSessionReference(cached.reference);
+      const key = getSessionReferenceKey(reference);
+      if (missingByKey.has(key) && !cachedByKey.has(key)) {
+        cachedByKey.set(key, canonicalSession(reference, cached.session));
+      }
+    }
+  }
+  const views = normalizedBookmarks.map(({ bookmark, key }) => {
+    const session = liveByKey.get(key) ?? cachedByKey.get(key);
+    if (session) return { ...bookmark, availability: "available", session };
+    return {
+      ...bookmark,
+      availability: options.knownAgentNames.has(bookmark.reference.agentName) ? "session-unavailable" : "agent-unavailable"
+    };
+  });
+  return views.sort(compareBookmarkViews);
+}
+
+// src/api/session-aliases-view.ts
+function aliasKey(reference) {
+  return `${reference.agentName.toLowerCase()}\0${reference.sessionId}`;
+}
+function buildAliasView(aliases) {
   return {
     size: aliases.size,
     get: (reference) => aliases.get(aliasKey(reference))?.alias,
@@ -591,9 +1398,28 @@ function buildAliasView() {
     entries: () => aliases.values()
   };
 }
+function readAliasView() {
+  try {
+    return buildAliasView(
+      new Map(listSessionAliases().map((alias) => [aliasKey(alias.reference), alias]))
+    );
+  } catch (error) {
+    if (!(error instanceof StateStorageUnavailableError)) {
+      appLogger.warn("api.session_aliases.load_failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    return null;
+  }
+}
+var EMPTY_ALIAS_VIEW = buildAliasView(/* @__PURE__ */ new Map());
 var cachedView = null;
 function loadAliasView() {
-  return cachedView ??= buildAliasView();
+  if (cachedView) return cachedView;
+  const loaded = readAliasView();
+  if (!loaded) return EMPTY_ALIAS_VIEW;
+  cachedView = loaded;
+  return loaded;
 }
 function invalidateAliasView() {
   cachedView = null;
@@ -622,7 +1448,9 @@ function findAliasSearchResults(query, options, scanResult, aliases, context = {
   const lookupSession = (agentName, sessionId) => {
     let byId = sessionsByAgent.get(agentName);
     if (!byId) {
-      byId = new Map((scanResult.byAgent[agentName] ?? []).map((item) => [item.id, item]));
+      byId = new Map(
+        (scanResult.byAgent[agentName] ?? []).map((item) => [item.reference.sessionId, item])
+      );
       sessionsByAgent.set(agentName, byId);
     }
     return byId.get(sessionId);
@@ -650,16 +1478,16 @@ function findAliasSearchResults(query, options, scanResult, aliases, context = {
 // src/api/handlers.ts
 var KNOWN_AGENT_NAMES = getAgentInfoMap({}).map((agent) => agent.name);
 var KNOWN_AGENT_NAME_SET = new Set(KNOWN_AGENT_NAMES);
-async function resolveProjectScope(cwd, sessions, resolver) {
+async function resolveProjectScope(cwd, sessions, resolver, signal) {
   const normalizedCwd = normalizeProjectDirectory(cwd);
   const matchingSession = sessions.find(
-    (session) => normalizeProjectDirectory(session.directory) === normalizedCwd && session.project_identity != null && session.project_identity_resolver_revision === PROJECT_IDENTITY_RESOLVER_REVISION && Boolean(session.project_identity_input_signature)
+    (session) => normalizeProjectDirectory(session.directory) === normalizedCwd && session.project_identity_resolver_revision === PROJECT_IDENTITY_RESOLVER_REVISION && Boolean(session.project_identity_input_signature)
   );
-  if (matchingSession?.project_identity) {
+  if (matchingSession) {
     return createProjectScopeMatcherFromIdentity(cwd, matchingSession.project_identity);
   }
   if (!resolver) throw new Error("Project identity resolver is unavailable");
-  const projection = await resolver.resolve(cwd);
+  const projection = await resolver.resolve(cwd, signal);
   return createProjectScopeMatcherFromIdentity(cwd, projection.identity);
 }
 function reportProjectScopeResolutionFailure(endpoint, error) {
@@ -668,6 +1496,14 @@ function reportProjectScopeResolutionFailure(endpoint, error) {
     error: error instanceof Error ? error.message : String(error)
   });
 }
+function projectScopeResolutionFailureResponse(c, endpoint, error) {
+  if (error instanceof ProjectIdentityRequestAbortedError) throw error;
+  reportProjectScopeResolutionFailure(endpoint, error);
+  if (error instanceof ProjectIdentityQueueFullError) {
+    return c.json({ error: "Project scope busy; retry later" }, 429);
+  }
+  return c.json({ error: "Project scope unavailable" }, 503);
+}
 function reportInvalidQueryParameter(endpoint, parameter, validationOutcome) {
   appLogger.warn("api.query_parameter.invalid", {
     endpoint,
@@ -684,22 +1520,8 @@ function parseDateWindowRequest(c, endpoint, defaults) {
     response: c.json({ error: `${outcome.parameter} ${outcome.error}` }, 400)
   };
 }
-function toSessionListItem(session) {
-  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) {
-  return {
-    agentName: getSessionAgentKey(session),
-    sessionId: session.id
-  };
+  return session.reference;
 }
 function handleGetConfig(c, defaults) {
   const payload = {
@@ -737,31 +1559,64 @@ function handleGetAgents(c, scanSource, defaults = {}) {
 }
 function handleGetProjects(c, scanSource, defaults = {}) {
   const scanResult = scanSource.getSnapshot();
+  const params = searchParams(c);
+  const limit = parseLimit(params.get("limit"), PROJECT_PAGE_LIMIT_POLICY);
+  if (limit.kind === "invalid") {
+    reportInvalidQueryParameter("projects", "limit", "rejected");
+    return c.json({ error: limit.error }, 400);
+  }
+  const projectIdentity = parseProjectIdentityFilter(
+    c.req.query("projectKind"),
+    c.req.query("projectKey")
+  );
+  if (projectIdentity === null) {
+    return c.json({ error: "projectKind and projectKey must form a valid project identity" }, 400);
+  }
   const window = parseDateWindowRequest(c, "projects", defaults);
   if (window.kind === "rejected") return window.response;
   const { from, to } = window;
   const analyticsRevision = getAnalyticsRevision();
-  const projects = getSnapshotAggregation(
+  const catalog = getSnapshotAggregation(
     scanSource,
     scanResult.sessions,
     ["projects", from, to, analyticsRevision],
     () => {
       const tree = getSnapshotSessionTree(scanSource, scanResult.sessions);
       const costFacts = listDashboardCostFacts({ from, to, includeModelCosts: false });
-      return {
-        projects: attachProjectMetricsFromTree(
-          listCachedProjectGroups(scanResult.sessions),
-          tree,
-          from,
-          to,
-          costFacts
-        ).filter(
-          (project) => project.sessionCount > 0 || project.messages > 0 || project.tokens > 0 || project.cost > 0
-        )
-      };
+      const projects2 = attachProjectMetricsFromTree(
+        listCachedProjectGroups(scanResult.sessions),
+        tree,
+        from,
+        to,
+        costFacts
+      ).filter(
+        (project) => project.sessionCount > 0 || project.messages > 0 || project.tokens > 0 || project.cost > 0
+      );
+      return { projects: projects2, summary: summarizeProjects(projects2) };
     }
   );
-  return c.json(projects);
+  const projects = projectIdentity ? catalog.projects.filter(
+    (project) => project.identityKind === projectIdentity.kind && project.identityKey === projectIdentity.key
+  ) : catalog.projects;
+  const page = paginateSnapshot(projects, {
+    cursor: params.get("cursor") ?? void 0,
+    limit: limit.value,
+    query: params,
+    snapshotIdentity: scanResult.sessions,
+    viewIdentity: catalog.projects
+  });
+  if (page.kind === "invalid_cursor") {
+    reportInvalidQueryParameter("projects", "cursor", "rejected");
+    return c.json({ error: "cursor is invalid for this request" }, 400);
+  }
+  if (page.kind === "stale_snapshot") {
+    return c.json({ error: "project snapshot changed; restart pagination" }, 409);
+  }
+  return c.json({
+    projects: page.items,
+    summary: projectIdentity ? summarizeProjects(projects) : catalog.summary,
+    ...page.nextCursor ? { nextCursor: page.nextCursor } : {}
+  });
 }
 async function handleGetSessions(c, scanSource, defaults = {}, resolver) {
   const scanResult = scanSource.getSnapshot();
@@ -788,10 +1643,14 @@ async function handleGetSessions(c, scanSource, defaults = {}, resolver) {
   let projectScope;
   if (cwd && !projectIdentity) {
     try {
-      projectScope = await resolveProjectScope(cwd, scanResult.sessions, resolver);
+      projectScope = await resolveProjectScope(
+        cwd,
+        scanResult.sessions,
+        resolver,
+        c.req.raw.signal
+      );
     } catch (error) {
-      reportProjectScopeResolutionFailure("sessions", error);
-      return c.json({ error: "Project scope unavailable" }, 503);
+      return projectScopeResolutionFailureResponse(c, "sessions", error);
     }
   }
   if (sessionQuery.agent.kind === "unknown") {
@@ -834,7 +1693,7 @@ async function handleGetSessions(c, scanSource, defaults = {}, resolver) {
     });
   }
   if (paginationRequested) {
-    const page = paginateSessionSnapshot(sessions, {
+    const page = paginateSnapshot(sessions, {
       cursor: params.get("cursor") ?? void 0,
       limit: sessionQuery.limit.value,
       query: params,
@@ -850,14 +1709,14 @@ async function handleGetSessions(c, scanSource, defaults = {}, resolver) {
     }
     return c.json({
       sessions: page.items.map(
-        (session) => toSessionListItem(aliases.decorate(session, getSessionHeadReference(session)))
+        (session) => toPublicSessionHead(aliases.decorate(session, getSessionHeadReference(session)))
       ),
       ...page.nextCursor ? { nextCursor: page.nextCursor } : {}
     });
   }
   return c.json({
     sessions: sessions.map(
-      (session) => toSessionListItem(aliases.decorate(session, getSessionHeadReference(session)))
+      (session) => toPublicSessionHead(aliases.decorate(session, getSessionHeadReference(session)))
     )
   });
 }
@@ -895,10 +1754,14 @@ async function handleSearchSessions(c, scanSource, defaults = {}, resolver) {
   let projectScope;
   if (cwd) {
     try {
-      projectScope = await resolveProjectScope(cwd, scanResult.sessions, resolver);
+      projectScope = await resolveProjectScope(
+        cwd,
+        scanResult.sessions,
+        resolver,
+        c.req.raw.signal
+      );
     } catch (error) {
-      reportProjectScopeResolutionFailure("search", error);
-      return c.json({ error: "Project scope unavailable" }, 503);
+      return projectScopeResolutionFailureResponse(c, "search", error);
     }
   }
   const { cwd: _cwd, ...searchOptions } = searchRequestOptions;
@@ -926,7 +1789,9 @@ async function handleSearchSessions(c, scanSource, defaults = {}, resolver) {
     resolvedSearchOptions.limit ?? 50
   );
   return c.json({
-    results: withParentContext(mergedResults, getSessionTree, aliases)
+    results: withParentContext(mergedResults, getSessionTree, aliases).map(
+      toPublicReferencedSessionHead
+    )
   });
 }
 async function handleGetFileActivity(c, defaults = {}, resolver) {
@@ -956,10 +1821,9 @@ async function handleGetFileActivity(c, defaults = {}, resolver) {
   let projectScope;
   if (cwd) {
     try {
-      projectScope = await resolveProjectScope(cwd, [], resolver);
+      projectScope = await resolveProjectScope(cwd, [], resolver, c.req.raw.signal);
     } catch (error) {
-      reportProjectScopeResolutionFailure("file-activity", error);
-      return c.json({ error: "Project scope unavailable" }, 503);
+      return projectScopeResolutionFailureResponse(c, "file-activity", error);
     }
   }
   const aliases = loadAliasView();
@@ -976,10 +1840,10 @@ async function handleGetFileActivity(c, defaults = {}, resolver) {
       from: window.from,
       to: window.to,
       limit: sessionQuery.limit.value
-    }).map((activity) => decorateFileActivity(activity, aliases))
+    }).map((activity) => toPublicReferencedSessionHead(decorateFileActivity(activity, aliases)))
   });
 }
-async function handleGetSessionData(c, scanSource, resolver) {
+async function handleGetSessionData(c, scanSource) {
   const startedAt = performance.now();
   const agentName = c.req.param("agent");
   const sessionId = c.req.param("id");
@@ -995,18 +1859,11 @@ async function handleGetSessionData(c, scanSource, resolver) {
       sessionId
     };
     const messageCursor = optionalQueryValue(c.req.query("messageCursor"));
-    const materialize = (fallback) => materializeSessionDetailResponse(scanSource.getSnapshot(), reference, {
-      ...messageCursor ? { messageCursor } : {},
-      ...fallback ? { projectIdentityFallback: fallback } : {}
-    });
-    let result = materialize();
-    if (result.status === "needs-identity") {
-      if (!resolver) throw new Error("Project identity resolver is unavailable");
-      result = materialize((await resolver.resolve(result.directory)).identity);
-    }
-    if (result.status === "needs-identity") {
-      throw new Error("Project identity fallback was not applied");
-    }
+    const result = materializeSessionDetailResponse(
+      scanSource.getSnapshot(),
+      reference,
+      messageCursor ? { messageCursor } : {}
+    );
     if (result.status === "unknown-agent") {
       return c.json({ error: `Unknown agent: ${agentName}` }, 404);
     }
@@ -1068,12 +1925,9 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
   if (dateWindow.kind === "rejected") return dateWindow.response;
   const { from, to, days } = resolveTimeWindow({
     mode: "dashboard",
-    query: {
-      days: c.req.query("days"),
-      from: c.req.query("from"),
-      to: c.req.query("to")
-    },
-    defaults
+    window: dateWindow,
+    days: c.req.query("days"),
+    defaultDays: defaults.days
   });
   const scope = {
     agent: optionalQueryValue(c.req.query("agent"))?.toLowerCase(),
@@ -1137,12 +1991,14 @@ function handleGetDashboard(c, scanSource, defaults = {}) {
   const aliases = loadAliasView();
   return c.json({
     ...data,
-    recentSessions: data.recentSessions.map((item) => ({
-      ...item,
-      session: aliases.decorate(item.session, item.reference)
-    })),
+    recentSessions: data.recentSessions.map(
+      (item) => toPublicReferencedSessionHead({
+        ...item,
+        session: aliases.decorate(item.session, item.reference)
+      })
+    ),
     recentFileActivities: data.recentFileActivities.map(
-      (activity) => decorateFileActivity(activity, aliases)
+      (activity) => toPublicReferencedSessionHead(decorateFileActivity(activity, aliases))
     )
   });
 }
@@ -1170,7 +2026,10 @@ function materializeStoredBookmarks(scanSource, bookmarks, aliases) {
     liveSessionsByReference: sessionIndex.byRouteKey,
     knownAgentNames: KNOWN_AGENT_NAME_SET,
     resolveCachedSessions: loadCachedSessionHeads
-  }).map((bookmark) => decorateBookmark(bookmark, aliases));
+  }).map((bookmark) => {
+    const decorated = decorateBookmark(bookmark, aliases);
+    return decorated.availability === "available" ? { ...decorated, session: toPublicSessionHead(decorated.session) } : decorated;
+  });
 }
 function handleGetBookmarks(c, scanSource) {
   return withStorageErrors(
@@ -1418,7 +2277,26 @@ data: ${JSON.stringify(data)}
 };
 
 // src/api/routes.ts
-function createSseResponse(eventSource, signal) {
+var MAX_ACTIVE_SSE_CONNECTIONS = 32;
+function createSseConnectionBudget(maxConnections) {
+  let activeConnections = 0;
+  return {
+    acquire() {
+      if (activeConnections >= maxConnections) return null;
+      activeConnections += 1;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        activeConnections -= 1;
+      };
+    },
+    activeCount() {
+      return activeConnections;
+    }
+  };
+}
+function createSseResponse(eventSource, signal, releaseConnection) {
   let cancelStream = () => {
   };
   let drainStream = () => {
@@ -1438,11 +2316,12 @@ function createSseResponse(eventSource, signal) {
         const cleanup = () => {
           if (isClosed) return false;
           isClosed = true;
-          buffer.close();
+          buffer?.close();
           if (heartbeat) clearInterval(heartbeat);
           unsubscribeSessions();
           unsubscribeScanStatus();
           signal.removeEventListener("abort", abortStream);
+          releaseConnection();
           return true;
         };
         abortStream = () => {
@@ -1452,20 +2331,25 @@ function createSseResponse(eventSource, signal) {
           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 = () => {
+        try {
+          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 });
+        } catch (error) {
           cleanup();
-        };
-        if (signal.aborted) abortStream();
-        else signal.addEventListener("abort", abortStream, { once: true });
+          throw error;
+        }
       },
       pull() {
         drainStream();
@@ -1485,6 +2369,7 @@ function createSseResponse(eventSource, signal) {
 }
 function createApiRoutes(scanSource, eventSource, options = {}) {
   const api = new Hono();
+  const sseConnections = createSseConnectionBudget(MAX_ACTIVE_SSE_CONNECTIONS);
   const listDefaults = {
     from: options.defaultSessionFrom,
     to: options.defaultSessionTo,
@@ -1493,158 +2378,51 @@ function createApiRoutes(scanSource, eventSource, options = {}) {
   api.get("/config", (c) => handleGetConfig(c, listDefaults));
   if (eventSource) {
     api.get("/status", (c) => handleGetScanStatus(c, eventSource));
-  }
-  api.get("/agents", (c) => handleGetAgents(c, scanSource, listDefaults));
-  api.get("/projects", (c) => handleGetProjects(c, scanSource, listDefaults));
-  api.get(
-    "/sessions",
-    (c) => handleGetSessions(c, scanSource, listDefaults, options.projectIdentityResolver)
-  );
-  api.get(
-    "/search",
-    (c) => handleSearchSessions(c, scanSource, listDefaults, options.projectIdentityResolver)
-  );
-  api.get(
-    "/file-activity",
-    (c) => handleGetFileActivity(c, listDefaults, options.projectIdentityResolver)
-  );
-  api.get(
-    "/sessions/:agent/:id",
-    (c) => handleGetSessionData(c, scanSource, options.projectIdentityResolver)
-  );
-  api.get("/dashboard", (c) => handleGetDashboard(c, scanSource, listDefaults));
-  api.get("/bookmarks", (c) => handleGetBookmarks(c, scanSource));
-  api.put("/bookmarks", (c) => handlePutBookmark(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) => {
-      const signal = options.shutdownSignal ? AbortSignal.any([c.req.raw.signal, options.shutdownSignal]) : c.req.raw.signal;
-      return createSseResponse(eventSource, signal);
-    });
-  }
-  return api;
-}
-
-// src/project-identity-resolver.ts
-import { Worker } from "worker_threads";
-var PROJECT_IDENTITY_RESOLVER_MAX_WORKERS = 2;
-var SHUTDOWN_ERROR_MESSAGE = "Project identity resolver shut down";
-function toError(error) {
-  return error instanceof Error ? error : new Error(String(error));
-}
-function isWorkerMessage(message) {
-  return typeof message === "object" && message !== null && "type" in message && (message.type === "resolved" && "requestId" in message && "projection" in message || message.type === "failed" && "requestId" in message && "error" in message);
-}
-var ThreadProjectIdentityResolver = class {
-  constructor(workerUrl, maxWorkers = PROJECT_IDENTITY_RESOLVER_MAX_WORKERS) {
-    this.workerUrl = workerUrl;
-    this.maxWorkers = maxWorkers;
-  }
-  workerUrl;
-  maxWorkers;
-  workers = /* @__PURE__ */ new Set();
-  queue = [];
-  nextRequestId = 1;
-  isShuttingDown = false;
-  resolve(cwd) {
-    if (this.isShuttingDown) return Promise.reject(new Error(SHUTDOWN_ERROR_MESSAGE));
-    return new Promise((resolve4, reject) => {
-      this.queue.push({ requestId: this.nextRequestId++, cwd, resolve: resolve4, reject });
-      this.pump();
-    });
-  }
-  async shutdown() {
-    if (this.isShuttingDown) return;
-    this.isShuttingDown = true;
-    const error = new Error(SHUTDOWN_ERROR_MESSAGE);
-    for (const request of this.queue.splice(0)) request.reject(error);
-    const workers = [...this.workers];
-    this.workers.clear();
-    for (const slot of workers) {
-      slot.closed = true;
-      slot.pending?.reject(error);
-      slot.pending = null;
-    }
-    await Promise.allSettled(workers.map(({ worker }) => worker.terminate()));
-  }
-  pump() {
-    while (!this.isShuttingDown && this.queue.length > 0) {
-      const slot = this.idleWorker() ?? this.createWorker();
-      if (!slot) return;
-      const request = this.queue.shift();
-      if (!request) return;
-      slot.pending = request;
-      try {
-        slot.worker.postMessage({
-          type: "resolve",
-          requestId: request.requestId,
-          cwd: request.cwd
+  }
+  api.get("/agents", (c) => handleGetAgents(c, scanSource, listDefaults));
+  api.get("/projects", (c) => handleGetProjects(c, scanSource, listDefaults));
+  api.get(
+    "/sessions",
+    (c) => handleGetSessions(c, scanSource, listDefaults, options.projectIdentityResolver)
+  );
+  api.get(
+    "/search",
+    (c) => handleSearchSessions(c, scanSource, listDefaults, options.projectIdentityResolver)
+  );
+  api.get(
+    "/file-activity",
+    (c) => handleGetFileActivity(c, listDefaults, options.projectIdentityResolver)
+  );
+  api.get("/sessions/:agent/:id", (c) => handleGetSessionData(c, scanSource));
+  api.get("/dashboard", (c) => handleGetDashboard(c, scanSource, listDefaults));
+  api.get("/bookmarks", (c) => handleGetBookmarks(c, scanSource));
+  api.put("/bookmarks", (c) => handlePutBookmark(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) => {
+      const releaseConnection = sseConnections.acquire();
+      if (!releaseConnection) {
+        appLogger.warn("api.sse.connection_limit_reached", {
+          active_connections: sseConnections.activeCount(),
+          connection_limit: MAX_ACTIVE_SSE_CONNECTIONS
         });
-      } catch (error) {
-        this.closeWorker(slot, toError(error));
+        c.header("Retry-After", "1");
+        return c.json({ error: "Too many active event streams" }, 429);
       }
-    }
-  }
-  idleWorker() {
-    for (const slot of this.workers) {
-      if (!slot.closed && slot.pending == null) return slot;
-    }
-    return null;
-  }
-  createWorker() {
-    if (this.workers.size >= this.maxWorkers) return null;
-    let worker;
-    try {
-      worker = new Worker(this.workerUrl);
-    } catch (error) {
-      this.rejectQueued(toError(error));
-      return null;
-    }
-    const slot = { worker, pending: null, closed: false };
-    this.workers.add(slot);
-    worker.unref();
-    worker.on("message", (message) => {
-      if (appLogger.consumeWorkerMessage(message)) return;
-      this.handleWorkerMessage(slot, message);
-    });
-    worker.on("error", (error) => this.closeWorker(slot, toError(error)));
-    worker.on("exit", (code) => {
-      if (!slot.closed) {
-        this.closeWorker(slot, new Error(`Project identity worker exited with code ${code}`));
+      const signal = options.shutdownSignal ? AbortSignal.any([c.req.raw.signal, options.shutdownSignal]) : c.req.raw.signal;
+      try {
+        return createSseResponse(eventSource, signal, releaseConnection);
+      } catch (error) {
+        releaseConnection();
+        throw error;
       }
     });
-    return slot;
-  }
-  handleWorkerMessage(slot, message) {
-    if (!isWorkerMessage(message) || slot.closed) return;
-    const request = slot.pending;
-    if (!request || message.requestId !== request.requestId) return;
-    slot.pending = null;
-    if (message.type === "resolved") request.resolve(message.projection);
-    else request.reject(new Error(message.error));
-    this.pump();
-  }
-  closeWorker(slot, error) {
-    if (slot.closed) return;
-    slot.closed = true;
-    this.workers.delete(slot);
-    const request = slot.pending;
-    slot.pending = null;
-    request?.reject(error);
-    if (!this.isShuttingDown) this.pump();
-  }
-  rejectQueued(error) {
-    for (const request of this.queue.splice(0)) request.reject(error);
   }
-};
-function createProjectIdentityResolver() {
-  return new ThreadProjectIdentityResolver(
-    new URL("./project-identity-worker.js", import.meta.url)
-  );
+  return api;
 }
 
 // src/loopback-authority.ts
@@ -1763,9 +2541,16 @@ function loopbackWriteGuard() {
 import { randomBytes, timingSafeEqual } from "crypto";
 import { readFileSync } from "fs";
 import { isIP as isIP2 } from "net";
-var REMOTE_ACCESS_QUERY_PARAM = "access_token";
+var ACCESS_TOKEN_QUERY_PARAM = "access_token";
 var RemoteTransportError = class extends Error {
 };
+function assertTrustedProxyListener(hostname, transport) {
+  if (transport.kind === "trusted-proxy" && !isLoopbackHostname(hostname)) {
+    throw new RemoteTransportError(
+      "--trust-proxy requires a loopback --host so clients cannot reach the HTTP backend directly."
+    );
+  }
+}
 function resolveRemoteTransport(request) {
   const hasCert = Boolean(request.tlsCertPath);
   const hasKey = Boolean(request.tlsKeyPath);
@@ -1790,16 +2575,45 @@ function resolveRemoteTransport(request) {
       );
     }
   }
-  if (request.trustProxy) return { kind: "trusted-proxy" };
+  if (request.trustProxy) {
+    const transport = { kind: "trusted-proxy" };
+    assertTrustedProxyListener(request.hostname, transport);
+    return transport;
+  }
   return isLoopbackHostname(request.hostname) ? { kind: "loopback" } : { kind: "plaintext" };
 }
 function resolveRemoteAccessPolicy(hostname, transport) {
+  assertTrustedProxyListener(hostname, transport);
   const bindCategory = isLoopbackHostname(hostname) ? "loopback" : "network";
+  const directLoopback = bindCategory === "loopback" && transport.kind === "loopback";
   return {
     bindCategory,
-    authenticationRequired: bindCategory === "network" || transport.kind !== "loopback"
+    remoteAccessRequired: !directLoopback
   };
 }
+function resolvePublicOrigin(value, transport) {
+  if (transport.kind !== "trusted-proxy") {
+    if (value) throw new RemoteTransportError("--public-url requires --trust-proxy.");
+    return void 0;
+  }
+  if (!value) {
+    throw new RemoteTransportError(
+      "--trust-proxy requires an HTTPS --public-url for browser startup links."
+    );
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new RemoteTransportError("--public-url must be a valid HTTPS origin.");
+  }
+  if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new RemoteTransportError(
+      "--public-url must be an HTTPS origin without credentials, path, query, or fragment."
+    );
+  }
+  return url.origin;
+}
 var FORWARDED_PROTO_HEADER = "X-Forwarded-Proto";
 function requireProxyTls() {
   return async (c, next) => {
@@ -1810,7 +2624,7 @@ function requireProxyTls() {
     await next();
   };
 }
-function createRemoteAccessToken() {
+function createAccessToken() {
   return randomBytes(32).toString("base64url");
 }
 function isLoopbackHostname(hostname) {
@@ -1833,12 +2647,12 @@ function requestToken(c) {
   const bearer = bearerToken(c);
   if (bearer) return bearer;
   if (c.req.method !== "GET") return void 0;
-  return c.req.query(REMOTE_ACCESS_QUERY_PARAM);
+  return c.req.query(ACCESS_TOKEN_QUERY_PARAM);
 }
-function remoteAccessAuth(expectedToken) {
+function accessTokenAuth(expectedToken) {
   return async (c, next) => {
     if (!tokenMatches(requestToken(c), expectedToken)) {
-      return c.json({ error: "Remote access authentication required" }, 401);
+      return c.json({ error: "API access token required" }, 401);
     }
     await next();
   };
@@ -1912,20 +2726,21 @@ async function createServer(port, store, options = {}) {
   const hostname = options.hostname ?? "127.0.0.1";
   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 publicOrigin = resolvePublicOrigin(options.publicUrl, transport);
+  const accessToken = options.accessToken || createAccessToken();
+  const loopbackAuthorityEnabled = !accessPolicy.remoteAccessRequired;
   const shutdownController = new AbortController();
   const projectIdentityResolver = options.projectIdentityResolver ?? createProjectIdentityResolver();
   let actualPort = null;
   appLogger.info("server.access_policy", {
     bind_category: accessPolicy.bindCategory,
     transport: transport.kind,
-    authentication: remoteAccessToken ? "token" : "none",
+    authentication: "token",
     loopback_authority: loopbackAuthorityEnabled ? "enabled" : "disabled"
   });
-  if (accessPolicy.authenticationRequired && !remoteAccessToken) {
+  if (accessPolicy.remoteAccessRequired && !options.remoteAccess && !options.accessToken) {
     throw new Error(
-      `Refusing to expose CodeSesh on ${hostname} without authentication. Add --remote-access to continue.`
+      `Refusing to expose CodeSesh on ${hostname} without explicit remote access. Add --remote-access to continue.`
     );
   }
   app.use(
@@ -1995,9 +2810,7 @@ async function createServer(port, store, options = {}) {
   if (transport.kind === "trusted-proxy") {
     app.use("/api/*", requireProxyTls());
   }
-  if (remoteAccessToken) {
-    app.use("/api/*", remoteAccessAuth(remoteAccessToken));
-  }
+  app.use("/api/*", accessTokenAuth(accessToken));
   app.use("/api/*", loopbackWriteGuard());
   app.use(
     "/api/*",
@@ -2053,16 +2866,17 @@ async function createServer(port, store, options = {}) {
     }
   }
   const scheme = transport.kind === "tls" ? "https" : "http";
-  const baseUrl = accessPolicy.bindCategory === "loopback" ? `${scheme}://localhost:${actualPort}` : `${scheme}://${hostname}:${actualPort}`;
-  const url = remoteAccessToken ? `${baseUrl}/?${REMOTE_ACCESS_QUERY_PARAM}=${encodeURIComponent(remoteAccessToken)}` : baseUrl;
+  const listenerUrl = accessPolicy.bindCategory === "loopback" ? `${scheme}://localhost:${actualPort}` : `${scheme}://${hostname}:${actualPort}`;
+  const url = `${publicOrigin ?? listenerUrl}/?${ACCESS_TOKEN_QUERY_PARAM}=${encodeURIComponent(accessToken)}`;
   appLogger.info("server.listen", {
     port: actualPort,
     requested_port: port,
     hostname,
-    remote_access: Boolean(remoteAccessToken),
+    public_origin: publicOrigin,
+    remote_access: accessPolicy.remoteAccessRequired,
     transport: transport.kind
   });
-  if (accessPolicy.authenticationRequired) {
+  if (accessPolicy.remoteAccessRequired) {
     appLogger.warn("server.listen.remote_access", {
       hostname,
       port: actualPort,
@@ -2090,6 +2904,7 @@ async function createServer(port, store, options = {}) {
   }
   return {
     url,
+    listenerUrl,
     shutdown: async () => {
       appLogger.info("server.shutdown", { port: actualPort });
       shutdownController.abort();
@@ -2113,6 +2928,87 @@ async function createServer(port, store, options = {}) {
 import { existsSync as existsSync4 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
+// src/agent-backfill-scheduler.ts
+var BACKFILL_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var PARTIAL_BACKFILL_RETRY_DELAY_MS = 5 * 60 * 1e3;
+var AgentBackfillScheduler = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  cacheIntegrityValidUntilByAgent = /* @__PURE__ */ new Map();
+  isShuttingDown = false;
+  needsBackfill(agent) {
+    const { from, to } = this.options.startupScanOptions;
+    if (from == null && to == null) return false;
+    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();
+    }
+    this.cacheIntegrityValidUntilByAgent.set(agent.name, lastSyncAt + BACKFILL_INTERVAL_MS);
+    return false;
+  }
+  enqueue(agentName) {
+    if (this.isShuttingDown || !this.options.lifecycle.enqueue(agentName)) return;
+    this.options.statusReporter.publishBackfillStatus();
+    this.pump();
+  }
+  shutdown() {
+    this.isShuttingDown = true;
+    this.options.lifecycle.cancelAll();
+    this.cacheIntegrityValidUntilByAgent.clear();
+  }
+  pump() {
+    if (this.isShuttingDown) return;
+    const attempt = this.options.lifecycle.startNext();
+    if (!attempt) return;
+    this.options.statusReporter.publishBackfillStatus();
+    void this.options.runAttempt(attempt).then((result) => this.complete(attempt, result)).catch((error) => this.reject(attempt, error));
+  }
+  complete(attempt, result) {
+    if (this.isShuttingDown) return;
+    const current = this.options.lifecycle.stateFor(attempt.agentName);
+    if (current?.status === "running" && current.attemptId === attempt.attemptId) {
+      this.options.statusReporter.flushProgressStatus(`backfill:${attempt.agentName}`);
+      if (this.options.lifecycle.complete(attempt, result)) {
+        if (result === "failed") {
+          this.cacheIntegrityValidUntilByAgent.delete(attempt.agentName);
+        } else if (result === "committed") {
+          if (current.completion?.completeness === "partial") {
+            this.cacheIntegrityValidUntilByAgent.delete(attempt.agentName);
+            this.options.scheduleRefresh(attempt.agentName, PARTIAL_BACKFILL_RETRY_DELAY_MS);
+            appLogger.info("scan.backfill.retry_scheduled", {
+              agent: attempt.agentName,
+              delay_ms: PARTIAL_BACKFILL_RETRY_DELAY_MS
+            });
+          } else {
+            this.cacheIntegrityValidUntilByAgent.set(
+              attempt.agentName,
+              Date.now() + BACKFILL_INTERVAL_MS
+            );
+          }
+        }
+        this.options.statusReporter.publishBackfillStatus();
+      }
+    }
+    this.pump();
+  }
+  reject(attempt, error) {
+    appLogger.error("scan.backfill.queue_error", { agent: attempt.agentName, error });
+    this.complete(attempt, "failed");
+  }
+};
+
 // src/agent-operation-scheduler.ts
 var PENDING_REFRESH_DELAY_MS = 100;
 var MAX_ADAPTIVE_REFRESH_DELAY_MS = 3e4;
@@ -2291,9 +3187,10 @@ var BackfillLifecycle = class {
   updateProgress(attempt, progress) {
     const current = this.matchingRunningAttempt(attempt);
     if (!current) return false;
+    const phaseChanged = progress.phase != null && progress.phase !== current.progress?.phase;
     this.attempts.set(attempt.agentName, {
       ...current,
-      progress: { ...current.progress, ...progress }
+      progress: phaseChanged ? { ...progress } : { ...current.progress, ...progress }
     });
     return true;
   }
@@ -2379,7 +3276,12 @@ var LiveSessionIndex = class {
     this.byAgent = Object.fromEntries(
       this.agents.flatMap((agent) => {
         if (this.scanFailures[agent.name] && !(agent.name in snapshot.byAgent)) return [];
-        return [[agent.name, sortSessions(snapshot.byAgent[agent.name] ?? [])]];
+        const sessions = snapshot.byAgent[agent.name] ?? [];
+        for (const session of sessions) {
+          assertSessionIdentity(session, agent.name);
+          assertIdentifiedSessionHead(session);
+        }
+        return [[agent.name, sortSessions(sessions)]];
       })
     );
     this.sessions = mergeSortedSessions(Object.values(this.byAgent));
@@ -2398,6 +3300,10 @@ var LiveSessionIndex = class {
     return this.agentsByName.get(agentName);
   }
   commitAgentSessions(agentName, nextSessions, candidateChangedIds = []) {
+    for (const session of nextSessions) {
+      assertSessionIdentity(session, agentName);
+      assertIdentifiedSessionHead(session);
+    }
     delete this.cacheFailures[agentName];
     delete this.scanFailures[agentName];
     const previousSessions = this.byAgent[agentName] ?? [];
@@ -2415,10 +3321,12 @@ var LiveSessionIndex = class {
     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 },
+      reference: session.reference,
       session
     }));
-    const previousSessionIds = new Set(previousSessions.map((session) => session.id));
+    const previousSessionIds = new Set(
+      previousSessions.map((session) => session.reference.sessionId)
+    );
     const newSessionRefs = changedSessionHeads.flatMap(
       ({ reference }) => previousSessionIds.has(reference.sessionId) ? [] : [reference]
     );
@@ -2432,14 +3340,13 @@ var LiveSessionIndex = class {
     return {
       type: "sessions-updated",
       changedAgents: [agentName],
-      newSessions: counts.new,
       newSessionRefs,
-      updatedSessions: counts.updated,
-      removedSessions: counts.removed,
       totalSessions: this.sessions.length,
       timestamp: Date.now(),
-      changedSessionHeads,
-      projectionRelatedSessionHeads: projectionContext.relatedSessionHeads,
+      changedSessionHeads: changedSessionHeads.map(toPublicReferencedSessionHead),
+      projectionRelatedSessionHeads: projectionContext.relatedSessionHeads.map(
+        toPublicReferencedSessionHead
+      ),
       projectionSessionOrder: projectionContext.sessionOrder,
       removedSessionRefs
     };
@@ -2503,6 +3410,16 @@ var PendingSearchIndexJobBatch = class {
       }
     }
   }
+  progress(progress, onError) {
+    for (const waiter of this.waiters) {
+      if (!waiter.agentNames.has(progress.agentName)) continue;
+      try {
+        waiter.onProgress?.(progress);
+      } catch (error) {
+        onError(error);
+      }
+    }
+  }
   merge(context, jobs, waiter) {
     this.context = context;
     this.waiters.push(waiter);
@@ -2542,10 +3459,16 @@ var PendingSearchIndexJobs = class {
   get changeCount() {
     return this.pendingBatch?.changeCount ?? 0;
   }
-  enqueue(id, context, jobs, onStarted) {
+  enqueue(id, context, jobs, onStarted, onProgress) {
     if (jobs.length === 0) return Promise.resolve();
     return new Promise((resolve4, reject) => {
-      const waiter = { resolve: resolve4, reject, onStarted };
+      const waiter = {
+        resolve: resolve4,
+        reject,
+        onStarted,
+        onProgress,
+        agentNames: new Set(jobs.map((job) => job.agentName))
+      };
       if (this.pendingBatch) {
         this.pendingBatch.merge(context, jobs, waiter);
       } else {
@@ -2597,7 +3520,7 @@ function mergeChanges(pending, job) {
     delete pending.meta[sessionId];
   }
   for (const change of job.changes) {
-    const sessionId = change.session.id;
+    const sessionId = change.session.reference.sessionId;
     pending.removedSessionIds.delete(sessionId);
     pending.changesBySessionId.set(sessionId, change);
     if (Object.hasOwn(job.meta, sessionId)) pending.meta[sessionId] = job.meta[sessionId];
@@ -2637,17 +3560,17 @@ var SearchIndexJobRunner = class {
   pendingJobs = new PendingSearchIndexJobs();
   pendingMaintenanceJobs = new PendingSearchIndexJobs();
   isShuttingDown = false;
-  enqueue(context, jobs, onStarted) {
-    return this.enqueueIn(this.pendingJobs, context, jobs, onStarted);
+  enqueue(context, jobs, onStarted, onProgress) {
+    return this.enqueueIn(this.pendingJobs, context, jobs, onStarted, onProgress);
   }
   enqueueMaintenance(context, jobs) {
     return this.enqueueIn(this.pendingMaintenanceJobs, context, jobs);
   }
-  enqueueIn(queue, context, jobs, onStarted) {
+  enqueueIn(queue, context, jobs, onStarted, onProgress) {
     if (jobs.length === 0) return Promise.resolve();
     if (this.isShuttingDown) return Promise.reject(new Error(SHUTDOWN_ERROR_MESSAGE2));
     const batchId = this.nextBatchId++;
-    const completion = queue.enqueue(batchId, context, jobs, onStarted);
+    const completion = queue.enqueue(batchId, context, jobs, onStarted, onProgress);
     if (this.activeBatch) {
       const snapshot = this.snapshot();
       appLogger.debug("search_index.worker_queued", {
@@ -2744,7 +3667,6 @@ var SearchIndexJobRunner = class {
       this.startNextBatch();
       return;
     }
-    worker.unref();
     this.worker = worker;
     this.activeBatch = batch;
     worker.on("message", (message) => {
@@ -2752,6 +3674,17 @@ var SearchIndexJobRunner = class {
       if (this.worker !== worker) return;
       const activeBatch = this.activeBatch;
       if (!activeBatch) return;
+      if (message.type === "publication-progress") {
+        const { agentName, stage } = message;
+        activeBatch.progress({ agentName, stage }, (error) => {
+          appLogger.error("search_index.worker_progress_listener_failed", {
+            batch_id: activeBatch.id,
+            context: activeBatch.context,
+            error: toError2(error)
+          });
+        });
+        return;
+      }
       if (message.type === "sync-result") {
         logSearchIndexSync(message.context, message.result);
         return;
@@ -2923,23 +3856,36 @@ var SearchIndexMaintenanceScheduler = class {
     }
     this.remaining = pending.total;
     this.publishStatus();
-    const cached = this.cachedSessionsByAgent.get(agentName) ?? loadCachedSessions(agentName);
+    let cached = this.cachedSessionsByAgent.get(agentName);
+    if (!cached) {
+      const outcome = readCachedSessions(agentName);
+      if (outcome.status === "failed") {
+        throw new Error(`Session cache read failed for ${agentName}`);
+      }
+      cached = outcome.value ?? void 0;
+    }
     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 }])
+      cached.sessions.map((session, sortIndex) => [
+        session.reference.sessionId,
+        { session, sortIndex }
+      ])
+    );
+    const changes = pending.sessionIds.flatMap(
+      (sessionId) => {
+        const change = sessionsById.get(sessionId);
+        return change ? [change] : [];
+      }
     );
-    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 sessionId = session.reference.sessionId;
+        const sessionMeta = cached.meta[sessionId];
+        return sessionMeta ? [[sessionId, sessionMeta]] : [];
       })
     );
     const job = {
@@ -3053,13 +3999,8 @@ var LatestValueThrottle = class {
 // src/scan-status-model.ts
 var ScanStatusModel = class {
   status = {
-    active: false,
     phase: "idle",
-    pendingAgents: [],
-    scanningAgents: [],
-    completedAgents: [],
     agentStatuses: {},
-    totalAgents: 0,
     updatedAt: Date.now(),
     backfill: { active: false, pendingAgents: [], completedAgents: [], failedAgents: [] },
     searchIndexMaintenance: {
@@ -3070,6 +4011,8 @@ var ScanStatusModel = class {
     }
   };
   snapshot() {
+    const agentLists = this.agentLists(this.status.agentStatuses);
+    const active = this.hasActiveAgents(this.status.agentStatuses);
     const backfill = {
       ...this.status.backfill,
       pendingAgents: [...this.status.backfill.pendingAgents],
@@ -3094,9 +4037,9 @@ var ScanStatusModel = class {
     return {
       type: "scan-status",
       ...this.status,
-      pendingAgents: [...this.status.pendingAgents],
-      scanningAgents: [...this.status.scanningAgents],
-      completedAgents: [...this.status.completedAgents],
+      active,
+      ...agentLists,
+      totalAgents: Object.keys(this.status.agentStatuses).length,
       agentStatuses: Object.fromEntries(
         Object.entries(this.status.agentStatuses).map(([agentName, status]) => [
           agentName,
@@ -3129,37 +4072,26 @@ var ScanStatusModel = class {
     );
     return this.set({
       ...this.status,
-      active: uniqueAgentNames.length > 0,
       phase: uniqueAgentNames.length > 0 ? phase : "idle",
-      pendingAgents: uniqueAgentNames,
-      scanningAgents: [],
-      completedAgents: [],
       agentStatuses,
-      totalAgents: uniqueAgentNames.length,
       startedAt: uniqueAgentNames.length > 0 ? now : void 0,
       updatedAt: now,
       completedAt: uniqueAgentNames.length > 0 ? void 0 : now
     });
   }
   setPhase(phase) {
-    if (!this.status.active) return null;
+    if (!this.hasActiveAgents(this.status.agentStatuses)) return null;
     return this.set({ ...this.status, phase, updatedAt: Date.now() });
   }
   beginAgent(agentName, sessionCount) {
-    if (!this.status.active)
+    if (!this.hasActiveAgents(this.status.agentStatuses)) {
       this.startBatch([agentName], "scanning", { [agentName]: sessionCount });
-    const pendingAgents = this.status.pendingAgents.filter((agent) => agent !== agentName);
-    const scanningAgents = [.../* @__PURE__ */ new Set([...this.status.scanningAgents, agentName])];
-    const completedAgents = this.status.completedAgents.filter((agent) => agent !== agentName);
+    }
     const existingStatus = this.status.agentStatuses[agentName];
     const now = Date.now();
     return this.set({
       ...this.status,
-      active: true,
       phase: this.status.phase === "initializing" ? "initializing" : "scanning",
-      pendingAgents,
-      scanningAgents,
-      completedAgents,
       agentStatuses: {
         ...this.status.agentStatuses,
         [agentName]: {
@@ -3172,7 +4104,6 @@ var ScanStatusModel = class {
           updatedAt: now
         }
       },
-      totalAgents: Math.max(this.status.totalAgents, pendingAgents.length + scanningAgents.length),
       updatedAt: now,
       completedAt: void 0
     });
@@ -3197,14 +4128,14 @@ var ScanStatusModel = class {
     };
     return this.set({
       ...this.status,
-      phase: this.activePhase(this.status.pendingAgents, this.status.scanningAgents, agentStatuses),
+      phase: this.activePhase(agentStatuses),
       agentStatuses,
       updatedAt: now
     });
   }
   queueAgentPublication(agentName) {
     const status = this.status.agentStatuses[agentName];
-    if (!this.status.active || !status || status.status !== "scanning" && status.status !== "finalizing") {
+    if (!this.hasActiveAgents(this.status.agentStatuses) || !status || status.status !== "scanning" && status.status !== "finalizing") {
       return null;
     }
     const now = Date.now();
@@ -3214,14 +4145,14 @@ var ScanStatusModel = class {
     };
     return this.set({
       ...this.status,
-      phase: this.activePhase(this.status.pendingAgents, this.status.scanningAgents, agentStatuses),
+      phase: this.activePhase(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") {
+    if (!this.hasActiveAgents(this.status.agentStatuses) || !status || status.status !== "scanning" && status.status !== "finalizing" && status.status !== "publish-queued") {
       return null;
     }
     const now = Date.now();
@@ -3231,16 +4162,12 @@ var ScanStatusModel = class {
     };
     return this.set({
       ...this.status,
-      phase: this.activePhase(this.status.pendingAgents, this.status.scanningAgents, agentStatuses),
+      phase: this.activePhase(agentStatuses),
       agentStatuses,
       updatedAt: now
     });
   }
   finishAgent(agentName, sessionCount, completion = { completeness: "complete" }) {
-    const pendingAgents = this.status.pendingAgents.filter((agent) => agent !== agentName);
-    const scanningAgents = this.status.scanningAgents.filter((agent) => agent !== agentName);
-    const completedAgents = [.../* @__PURE__ */ new Set([...this.status.completedAgents, agentName])];
-    const isActive = pendingAgents.length > 0 || scanningAgents.length > 0;
     const now = Date.now();
     const previousStatus = this.status.agentStatuses[agentName];
     const total = previousStatus?.total ?? previousStatus?.processed;
@@ -3258,46 +4185,37 @@ var ScanStatusModel = class {
         completedAt: now
       }
     };
+    const isActive = this.hasActiveAgents(agentStatuses);
     return this.set({
       ...this.status,
-      active: isActive,
-      phase: isActive ? this.activePhase(pendingAgents, scanningAgents, agentStatuses) : "idle",
-      pendingAgents,
-      scanningAgents,
-      completedAgents,
+      phase: isActive ? this.activePhase(agentStatuses) : "idle",
       agentStatuses,
       updatedAt: now,
       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];
+    const 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
+      }
+    };
+    const isActive = this.hasActiveAgents(agentStatuses);
     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
-        }
-      },
+      phase: isActive ? this.activePhase(agentStatuses) : "idle",
+      agentStatuses,
       updatedAt: now,
       completedAt: isActive ? void 0 : now
     });
@@ -3306,10 +4224,7 @@ var ScanStatusModel = class {
     const now = Date.now();
     return this.set({
       ...this.status,
-      active: false,
       phase: "idle",
-      pendingAgents: [],
-      scanningAgents: [],
       agentStatuses: Object.fromEntries(
         Object.entries(this.status.agentStatuses).map(([agentName, status]) => [
           agentName,
@@ -3359,7 +4274,8 @@ var ScanStatusModel = class {
       updatedAt: Date.now()
     });
   }
-  activePhase(pendingAgents, scanningAgents, agentStatuses) {
+  activePhase(agentStatuses) {
+    const { pendingAgents, scanningAgents } = this.agentLists(agentStatuses);
     if (pendingAgents.length === 0 && scanningAgents.length > 0 && scanningAgents.every((agentName) => {
       const status = agentStatuses[agentName]?.status;
       return status === "finalizing" || status === "publish-queued" || status === "publishing";
@@ -3368,6 +4284,22 @@ var ScanStatusModel = class {
     }
     return this.status.phase === "initializing" ? "initializing" : "scanning";
   }
+  agentLists(agentStatuses) {
+    const pendingAgents = [];
+    const scanningAgents = [];
+    const completedAgents = [];
+    for (const [agentName, status] of Object.entries(agentStatuses)) {
+      if (status.status === "pending") pendingAgents.push(agentName);
+      else if (status.status === "complete") completedAgents.push(agentName);
+      else if (status.status !== "failed") scanningAgents.push(agentName);
+    }
+    return { pendingAgents, scanningAgents, completedAgents };
+  }
+  hasActiveAgents(agentStatuses) {
+    return Object.values(agentStatuses).some(
+      (status) => status.status !== "complete" && status.status !== "failed"
+    );
+  }
   set(status) {
     this.status = status;
     return this.snapshot();
@@ -3580,7 +4512,7 @@ var SearchIndexPublisher = class {
         ...job,
         publicationId: details.publicationId
       }));
-      await (details.onStarted ? this.options.jobs.enqueue(context, publicationJobs, details.onStarted) : this.options.jobs.enqueue(context, publicationJobs));
+      await (details.onProgress ? this.options.jobs.enqueue(context, publicationJobs, details.onStarted, details.onProgress) : details.onStarted ? this.options.jobs.enqueue(context, publicationJobs, details.onStarted) : this.options.jobs.enqueue(context, publicationJobs));
     } catch (error) {
       appLogger.error("session.publication.failed", {
         publication_id: details.publicationId,
@@ -3599,29 +4531,109 @@ var SearchIndexPublisher = class {
   }
 };
 
-// src/agent-sync-engine.ts
-var REFRESH_DEBOUNCE_MS = 200;
-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;
-var SOURCE_FAILURE_SUMMARY_MAX_LENGTH = 160;
-function buildPersistenceDiff(previousSessions, nextSessions, candidateChangedIds = [], completeness = "complete", explicitRemovedSessionIds = []) {
-  const { changes, removedSessionIds } = computeSessionDiff(
-    previousSessions,
-    nextSessions,
-    candidateChangedIds,
-    sessionSignature
-  );
-  if (completeness === "complete") {
-    return { changedSessions: changes, removedSessionIds };
+// src/session-publication.ts
+var SessionPublicationCoordinator = class {
+  constructor(indexPublisher, sessionIndex) {
+    this.indexPublisher = indexPublisher;
+    this.sessionIndex = sessionIndex;
+  }
+  indexPublisher;
+  sessionIndex;
+  listeners = /* @__PURE__ */ new Set();
+  isShuttingDown = false;
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  markShuttingDown() {
+    this.isShuttingDown = true;
+  }
+  async commit(publication) {
+    const publicationId = this.indexPublisher.publicationId(
+      publication.context,
+      publication.agentName
+    );
+    await this.indexPublisher.commitSearchIndex(publication.context, [publication.indexJob], {
+      publicationId,
+      agent: publication.agentName,
+      ...publication.onPublishing ? { onStarted: publication.onPublishing } : {},
+      ...publication.onPublicationProgress ? { onProgress: publication.onPublicationProgress } : {}
+    });
+    const diffStartedAt = performance.now();
+    const event = this.sessionIndex.commitAgentSessions(
+      publication.agentName,
+      publication.sessions,
+      publication.candidateChangedIds
+    );
+    const diffDuration = performance.now() - diffStartedAt;
+    const result = { durableCommitted: true, event, diffDuration };
+    this.runPostCommit(publication, "worker_commit", () => publication.stagedRun?.commit());
+    this.runPostCommit(publication, "callback", () => publication.onCommitted?.(result));
+    this.runPostCommit(
+      publication,
+      "notification",
+      () => this.emit({
+        agentName: publication.agentName,
+        sessions: this.sessionIndex.snapshot().byAgent[publication.agentName] ?? [],
+        event
+      })
+    );
+    this.runPostCommit(
+      publication,
+      "logging",
+      () => appLogger.info("session.publication.published", {
+        publication_id: publicationId,
+        context: publication.context,
+        agent: publication.agentName,
+        sessions: publication.sessions.length,
+        has_event: event != null
+      })
+    );
+    return result;
+  }
+  runPostCommit(publication, stage, action) {
+    try {
+      action();
+    } catch (error) {
+      try {
+        appLogger.error("session.publication.post_commit_error", {
+          context: publication.context,
+          agent: publication.agentName,
+          stage,
+          error
+        });
+      } catch {
+      }
+    }
+  }
+  emit(change) {
+    if (this.isShuttingDown) return;
+    for (const listener of this.listeners) {
+      try {
+        listener(change);
+      } catch (error) {
+        appLogger.error("session.publication.post_commit_error", {
+          agent: change.agentName,
+          error
+        });
+      }
+    }
   }
-  const explicitRemovals = new Set(explicitRemovedSessionIds);
+};
+
+// src/agent-sync-engine.ts
+function countSessionUpdates(event) {
+  if (!event) return { newSessions: 0, updatedSessions: 0, removedSessions: 0 };
   return {
-    changedSessions: changes,
-    removedSessionIds: removedSessionIds.filter((sessionId) => explicitRemovals.has(sessionId))
+    newSessions: event.newSessionRefs.length,
+    updatedSessions: event.changedSessionHeads.length - event.newSessionRefs.length,
+    removedSessions: event.removedSessionRefs.length
   };
 }
+var REFRESH_DEBOUNCE_MS = 200;
+var EMPTY_AGENT_REFRESH_DEBOUNCE_MS = 3e4;
+var SEARCH_INDEX_BULK_PENDING_PATH_THRESHOLD = 100;
+var SOURCE_FAILURE_SUMMARY_MAX_LENGTH = 160;
 function buildScanCompletion(completeness, sourceFailures) {
   if (sourceFailures.length === 0) return { completeness };
   const firstFailure = sourceFailures[0];
@@ -3632,9 +4644,6 @@ function buildScanCompletion(completeness, sourceFailures) {
     sourceFailureSummary: summary.length > SOURCE_FAILURE_SUMMARY_MAX_LENGTH ? `${summary.slice(0, SOURCE_FAILURE_SUMMARY_MAX_LENGTH - 1)}\u2026` : summary
   };
 }
-function restoreAgentCacheMeta(agent, cached) {
-  agent.setSessionMetaMap(new Map(Object.entries(cached.meta)));
-}
 var AgentSyncEngine = class {
   constructor(options) {
     this.options = options;
@@ -3649,6 +4658,17 @@ var AgentSyncEngine = class {
       snapshot: () => this.sessionIndex.snapshot(),
       readCachedSessions: (agentName) => this.readCachedSessionsOrWarn("search.index", agentName)
     });
+    this.sessionPublication = new SessionPublicationCoordinator(
+      this.indexPublisher,
+      this.sessionIndex
+    );
+    this.backfillScheduler = new AgentBackfillScheduler({
+      lifecycle: this.backfills,
+      statusReporter: this.statusReporter,
+      startupScanOptions: this.startupScanOptions(),
+      runAttempt: (attempt) => this.runBackfill(attempt),
+      scheduleRefresh: (agentName, delayMs) => this.scheduler.schedule(agentName, delayMs)
+    });
     this.searchIndexMaintenance = new SearchIndexMaintenanceScheduler(
       this.searchIndexJobs,
       (status) => this.statusReporter.updateSearchIndexMaintenance(status)
@@ -3659,14 +4679,13 @@ var AgentSyncEngine = class {
   scheduler;
   sessionIndex = new LiveSessionIndex();
   backfills = new BackfillLifecycle();
-  cacheIntegrityValidUntilByAgent = /* @__PURE__ */ new Map();
-  sessionsChangedListeners = /* @__PURE__ */ new Set();
+  backfillScheduler;
   statusReporter;
   indexPublisher;
+  sessionPublication;
   searchIndexJobs;
   searchIndexMaintenance;
   backgroundRefreshTimer = null;
-  isShuttingDown = false;
   initialize(snapshot, options = {}) {
     this.sessionIndex.initialize(snapshot, options);
     this.lastRefreshAtByAgent.clear();
@@ -3691,8 +4710,7 @@ var AgentSyncEngine = class {
     return this.statusReporter.status();
   }
   subscribeSessionsChanged(listener) {
-    this.sessionsChangedListeners.add(listener);
-    return () => this.sessionsChangedListeners.delete(listener);
+    return this.sessionPublication.subscribe(listener);
   }
   subscribeStatusChanged(listener) {
     return this.statusReporter.subscribe(listener);
@@ -3726,7 +4744,7 @@ var AgentSyncEngine = class {
     await this.scheduler.refresh(agentName);
   }
   async shutdown() {
-    this.isShuttingDown = true;
+    this.sessionPublication.markShuttingDown();
     const schedulerSnapshot = this.scheduler.snapshot();
     const activeOperations = {
       agent_operations: schedulerSnapshot.activeOperations,
@@ -3742,10 +4760,9 @@ var AgentSyncEngine = class {
       clearTimeout(this.backgroundRefreshTimer);
       this.backgroundRefreshTimer = null;
     }
-    this.backfills.cancelAll();
+    this.backfillScheduler.shutdown();
     this.searchIndexMaintenance.stop();
     this.statusReporter.markShuttingDown();
-    this.cacheIntegrityValidUntilByAgent.clear();
     const searchIndexSnapshot = this.searchIndexJobs.snapshot();
     appLogger.info("search_index.shutdown.started", {
       active_batch_id: searchIndexSnapshot.activeBatchId,
@@ -3761,19 +4778,16 @@ var AgentSyncEngine = class {
       pending_batches: stoppedSearchIndexSnapshot.pendingBatches
     });
   }
-  emitSessionsChanged(change) {
-    if (this.isShuttingDown) return;
-    for (const listener of this.sessionsChangedListeners) {
-      try {
-        listener(change);
-      } catch (error) {
-        this.reportPostCommitError("session.publication", change.agentName, error);
-      }
-    }
-  }
   reportPostCommitError(operation, agentName, error) {
     appLogger.error(`${operation}.post_commit_error`, { agent: agentName, error });
   }
+  commitRefreshChangeCheck(agentName, commit) {
+    try {
+      commit?.();
+    } catch (error) {
+      this.reportPostCommitError("scan.refresh", agentName, error);
+    }
+  }
   finishCommittedAgentScan(agentName, completion) {
     try {
       this.statusReporter.finishAgentScan(agentName, completion);
@@ -3789,62 +4803,50 @@ var AgentSyncEngine = class {
   async performRefresh(agentName) {
     this.statusReporter.beginAgentScan(agentName);
     const startedAt = performance.now();
-    let failed = false;
-    let durableCommitted = false;
     let cached = null;
-    let result = "failed";
-    let completion = { completeness: "complete" };
+    let refresh = {
+      result: "failed",
+      completion: { completeness: "complete" }
+    };
     try {
       if (this.findAgent(agentName))
         cached = this.readCachedSessionsOrWarn("scan.refresh", agentName);
-      const refresh = await this.runRefresh(agentName, cached, startedAt, (committedCompletion) => {
-        durableCommitted = true;
-        completion = committedCompletion;
-        result = "committed";
-      });
-      result = refresh.result;
-      completion = refresh.completion;
+      refresh = await this.runRefresh(agentName, cached, startedAt);
     } catch (error) {
-      if (durableCommitted) {
-        this.reportPostCommitError("scan.refresh", agentName, error);
-        result = "committed";
+      const failure = toError2(error);
+      if (failure instanceof AgentUnavailableDuringScanError) {
+        appLogger.warn("scan.refresh.worker_agent_unavailable", {
+          agent: agentName,
+          error: failure.message
+        });
       } else {
-        this.options.workerRunner.discard?.(agentName);
-        failed = true;
-        const failure = toError2(error);
-        if (failure instanceof AgentUnavailableDuringScanError) {
-          appLogger.warn("scan.refresh.worker_agent_unavailable", {
-            agent: agentName,
-            error: failure.message
-          });
-        } else {
-          appLogger.error("scan.refresh.error", { agent: agentName, error });
-        }
-        console.error(`[${agentName}] Session refresh failed:`, error);
-        this.statusReporter.failAgent(agentName, failure.message);
+        appLogger.error("scan.refresh.error", { agent: agentName, error });
       }
+      console.error(`[${agentName}] Session refresh failed:`, error);
+      this.statusReporter.failAgent(agentName, failure.message);
     }
     try {
-      if (!failed) {
-        if (durableCommitted) this.finishCommittedAgentScan(agentName, completion);
-        else this.statusReporter.finishAgentScan(agentName, completion);
+      if (refresh.result !== "failed") {
+        if (refresh.result === "committed")
+          this.finishCommittedAgentScan(agentName, refresh.completion);
+        else this.statusReporter.finishAgentScan(agentName, refresh.completion);
       }
     } catch (error) {
-      if (!durableCommitted) throw error;
+      if (refresh.result !== "committed") throw error;
       this.reportPostCommitError("scan.refresh", agentName, error);
     }
     try {
       const agent = this.findAgent(agentName);
-      if (agent && this.needsBackfill(agent, cached, failed || result === "committed")) {
+      if (agent && this.backfillScheduler.needsBackfill(agent)) {
         this.enqueueBackfill(agentName);
       }
       if (agent) this.searchIndexMaintenance.enqueue(agentName);
     } catch (error) {
       appLogger.warn("scan.refresh.backfill_probe_failed", { agent: agentName, error });
     }
-    return result;
+    return refresh.result;
   }
-  async runRefresh(agentName, cached, startedAt, onDurableCommit) {
+  async runRefresh(agentName, cached, startedAt) {
     const pendingPathCount = this.scheduler.takePendingSignalCount(agentName);
     const agent = this.findAgent(agentName);
     if (!agent) {
@@ -3854,8 +4856,8 @@ var AgentSyncEngine = class {
     const previousSessions = this.sessionIndex.snapshot().byAgent[agentName] ?? [];
     const refreshBaseline = cached?.sessions ?? previousSessions;
     const cacheTimestamp = cached?.timestamp ?? this.lastRefreshAtByAgent.get(agentName) ?? 0;
-    if (cached) restoreAgentCacheMeta(agent, cached);
-    const durableMeta = new Map(agent.getSessionMetaMap());
+    if (cached) agent.restoreSessionCacheMeta(cached.meta);
+    const durableMeta = agent.snapshotSessionCacheMeta();
     const durableLastRefreshAt = this.lastRefreshAtByAgent.get(agentName);
     const initialization = readAgentCacheInitialization(agentName);
     if (initialization.status === "failed") {
@@ -3866,28 +4868,33 @@ var AgentSyncEngine = class {
       return { result: "unchanged", completion: { completeness: "complete" } };
     }
     const isInitialized = initialization.value;
-    const availabilityStartedAt = performance.now();
-    const isAvailable = agent.isAvailable();
-    const availabilityDuration = performance.now() - availabilityStartedAt;
+    const refresh = await selectAgentRefresh(agent, {
+      initialized: isInitialized,
+      sinceTimestamp: cacheTimestamp,
+      cachedSessions: refreshBaseline
+    });
+    const availabilityDuration = refresh.availabilityDurationMs;
     let strategyResult;
-    if (!isAvailable) {
+    if (refresh.kind === "unavailable") {
       strategyResult = this.refreshUnavailableAgent(agentName);
-    } else if (!isInitialized) {
+    } else if (refresh.kind === "initialize") {
       strategyResult = await this.initializeAgent(agent, previousSessions);
-    } else if (cached && agent instanceof FileSystemSessionSource) {
-      strategyResult = await this.syncAgentSources(agent, cached, startedAt);
-    } else if (refreshBaseline.length > 0) {
-      strategyResult = await this.refreshChangedAgent(
+    } else if (refresh.kind === "synchronize") {
+      strategyResult = await this.syncAgentSources(
         agent,
-        refreshBaseline,
-        cacheTimestamp,
+        cached ?? {
+          sessions: refreshBaseline,
+          meta: durableMeta
+        },
         startedAt
       );
     } else {
-      strategyResult = await this.scanAgentFully(agent, previousSessions);
+      strategyResult = await this.refreshChangedAgent(agent, refresh, refreshBaseline, startedAt);
     }
+    const stagedRun = strategyResult.workerRun;
     if (strategyResult.status === "unchanged") {
-      this.options.workerRunner.commit?.(agentName);
+      stagedRun?.commit();
+      this.commitRefreshChangeCheck(agentName, strategyResult.commitChangeCheck);
       return {
         result: "unchanged",
         completion: buildScanCompletion(strategyResult.completeness, strategyResult.sourceFailures)
@@ -3895,14 +4902,17 @@ var AgentSyncEngine = class {
     }
     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 persistenceDiff = strategyResult.publication.kind === "changes" ? strategyResult.publication.diff : null;
+    const publicationSessions = strategyResult.publication.kind === "full" ? strategyResult.publication.sessions : nextSessions;
+    const explicitRemovedSessionIds = strategyResult.publication.kind === "full" ? strategyResult.publication.explicitRemovedSessionIds : [];
+    const publicationSessionIds = new Set(
+      publicationSessions.map((session) => session.reference.sessionId)
+    );
     const missingBaselineSessions = refreshBaseline.reduce(
-      (count, session) => count + Number(!publicationSessionIds.has(session.id)),
+      (count, session) => count + Number(!publicationSessionIds.has(session.reference.sessionId)),
       0
     );
-    const replacementDeleteCandidates = persistenceDiff ? persistenceDiff.removedSessionIds.length : strategyResult.completeness === "complete" ? missingBaselineSessions : strategyResult.explicitRemovedSessionIds.length;
+    const replacementDeleteCandidates = persistenceDiff ? persistenceDiff.removedSessionIds.length : strategyResult.completeness === "complete" ? missingBaselineSessions : explicitRemovedSessionIds.length;
     appLogger.info("scan.refresh.persistence_candidate", {
       agent: agentName,
       scope_from: strategyResult.scope.from,
@@ -3912,7 +4922,7 @@ var AgentSyncEngine = class {
       payload_sessions: publicationSessions.length,
       delete_candidates: replacementDeleteCandidates
     });
-    const changedSessionIds = persistenceDiff ? new Set(persistenceDiff.changedSessions.map(({ session }) => session.id)) : void 0;
+    const changedSessionIds = persistenceDiff ? new Set(persistenceDiff.changedSessions.map(({ session }) => session.reference.sessionId)) : void 0;
     const persistStartedAt = performance.now();
     const persistentJob = persistenceDiff ? {
       kind: "changes",
@@ -3929,7 +4939,7 @@ var AgentSyncEngine = class {
       sessions: publicationSessions,
       meta: buildAgentCacheMeta(agent),
       completeness: strategyResult.completeness,
-      removedSessionIds: strategyResult.explicitRemovedSessionIds,
+      removedSessionIds: explicitRemovedSessionIds,
       saveCache: true,
       ...searchIndexOptions ? { searchIndexOptions } : {}
     };
@@ -3938,59 +4948,59 @@ var AgentSyncEngine = class {
       strategyResult.sourceFailures
     );
     this.statusReporter.queueAgentPublication(agentName);
-    let publicationCommitted = false;
     let publication;
     try {
-      publication = await this.commitSessionPublication({
+      publication = await this.sessionPublication.commit({
         context: "scan.refresh",
         agentName,
         sessions: nextSessions,
-        candidateChangedIds: strategyResult.preciseChangedIds ?? [],
+        candidateChangedIds: strategyResult.publication.kind === "changes" ? strategyResult.publication.candidateChangedIds : [],
         indexJob: persistentJob,
-        onPublishing: () => this.statusReporter.beginAgentPublishing(agentName),
-        onCommitted: () => {
-          publicationCommitted = true;
-          onDurableCommit(completion);
-        }
+        stagedRun,
+        onPublishing: () => this.statusReporter.beginAgentPublishing(agentName)
       });
     } catch (error) {
-      if (!publicationCommitted) {
-        agent.setSessionMetaMap(durableMeta);
-        if (durableLastRefreshAt == null) this.lastRefreshAtByAgent.delete(agentName);
-        else this.lastRefreshAtByAgent.set(agentName, durableLastRefreshAt);
-      }
+      stagedRun?.discard();
+      agent.restoreSessionCacheMeta(durableMeta);
+      if (durableLastRefreshAt == null) this.lastRefreshAtByAgent.delete(agentName);
+      else this.lastRefreshAtByAgent.set(agentName, durableLastRefreshAt);
       throw error;
     }
-    this.options.workerRunner.commit?.(agentName);
+    this.commitRefreshChangeCheck(agentName, strategyResult.commitChangeCheck);
     const persistDuration = performance.now() - persistStartedAt;
-    logSearchIndexSync("scan.refresh", null, { pending_paths: pendingPathCount });
     const totalDurationMs = performance.now() - startedAt;
-    this.scheduler.recordRefreshDuration(agentName, totalDurationMs);
-    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
+    try {
+      logSearchIndexSync("scan.refresh", null, { pending_paths: pendingPathCount });
+      this.scheduler.recordRefreshDuration(agentName, totalDurationMs);
+      const sessionUpdateCounts = countSessionUpdates(publication.event);
+      appLogger.info(
+        strategyResult.sourceFailures.length > 0 ? "scan.refresh.partial" : "scan.refresh.done",
+        {
+          agent: agentName,
+          duration_ms: Math.round(totalDurationMs),
+          sessions: nextSessions.length,
+          new_sessions: sessionUpdateCounts.newSessions,
+          updated_sessions: sessionUpdateCounts.updatedSessions,
+          removed_sessions: sessionUpdateCounts.removedSessions,
+          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
+        });
       }
-    );
-    if (strategyResult.sourceFailures.length > 0) {
-      appLogger.warn("scan.refresh.source_failures", {
-        agent: agentName,
-        failures: strategyResult.sourceFailures
-      });
+    } catch (error) {
+      this.reportPostCommitError("scan.refresh", agentName, error);
     }
     return { result: "committed", completion };
   }
@@ -4001,184 +5011,242 @@ var AgentSyncEngine = class {
    * empty database.
    */
   refreshUnavailableAgent(agentName) {
-    this.lastRefreshAtByAgent.set(agentName, Date.now());
     const previousSessions = this.sessionIndex.snapshot().byAgent[agentName] ?? [];
     if (previousSessions.length > 0) {
       appLogger.warn("scan.refresh.agent_unavailable", {
         agent: agentName,
         retained_sessions: previousSessions.length
       });
-      return this.refreshStrategyResult(previousSessions, "partial", {}, { status: "unchanged" });
+      return {
+        ...this.refreshStrategyBase(previousSessions, "partial", {}),
+        status: "unchanged"
+      };
     }
-    return this.refreshStrategyResult([], "partial", {});
+    return {
+      ...this.refreshStrategyBase([], "partial", {}),
+      status: "continue",
+      publication: { kind: "full", sessions: [], explicitRemovedSessionIds: [] }
+    };
   }
   async initializeAgent(agent, previousSessions) {
     this.statusReporter.setScanPhase("initializing");
     const scanStartedAt = performance.now();
     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, result.completeness, scope, {
-      fullScanSessions: sessions,
-      explicitRemovedSessionIds: result.explicitRemovedSessionIds,
-      scanDuration: performance.now() - scanStartedAt,
-      sourceFailures: result.sourceFailures ?? []
-    });
+    const workerRun = await this.runWorker(agent, previousSessions, { kind: "full-scan" }, scope);
+    try {
+      const { result } = workerRun;
+      agent.restoreSessionCacheMeta(result.meta);
+      const sessions = attachMissingProjectIdentities(result.sessions);
+      this.lastRefreshAtByAgent.set(agent.name, Date.now());
+      return {
+        ...this.refreshStrategyBase(sessions, result.completeness, scope, {
+          scanDuration: performance.now() - scanStartedAt,
+          sourceFailures: result.sourceFailures ?? [],
+          workerRun
+        }),
+        status: "continue",
+        publication: {
+          kind: "full",
+          sessions,
+          explicitRemovedSessionIds: result.explicitRemovedSessionIds
+        }
+      };
+    } catch (error) {
+      workerRun.discard();
+      throw error;
+    }
   }
-  async syncAgentSources(agent, cached, refreshStartedAt) {
+  async syncAgentSources(agent, baseline, refreshStartedAt) {
     const scanStartedAt = performance.now();
     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)));
-    const sessions = attachMissingProjectIdentities(result.sessions);
-    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 && (result.sourceFailures?.length ?? 0) === 0) {
-      this.logUnchangedRefresh(agent.name, refreshStartedAt);
-      return this.refreshStrategyResult(sessions, result.completeness, scope, {
-        status: "unchanged",
-        scanDuration: performance.now() - scanStartedAt
+    const workerRun = await this.runWorker(
+      agent,
+      baseline.sessions,
+      { kind: "source-refresh" },
+      scope,
+      {
+        meta: baseline.meta
+      }
+    );
+    try {
+      const { result } = workerRun;
+      agent.restoreSessionCacheMeta(result.meta);
+      const sessions = attachMissingProjectIdentities(result.sessions);
+      const preciseChangedIds = result.changedIds ?? [];
+      const persistenceDiff = buildSessionPersistenceDiff(baseline.sessions, sessions, {
+        candidateChangedIds: preciseChangedIds
       });
+      this.lastRefreshAtByAgent.set(agent.name, Date.now());
+      if (persistenceDiff.changedSessions.length === 0 && persistenceDiff.removedSessionIds.length === 0 && (result.sourceFailures?.length ?? 0) === 0) {
+        this.logUnchangedRefresh(agent.name, refreshStartedAt);
+        return {
+          ...this.refreshStrategyBase(sessions, result.completeness, scope, {
+            scanDuration: performance.now() - scanStartedAt,
+            workerRun
+          }),
+          status: "unchanged"
+        };
+      }
+      return {
+        ...this.refreshStrategyBase(sessions, result.completeness, scope, {
+          scanDuration: performance.now() - scanStartedAt,
+          sourceFailures: result.sourceFailures ?? [],
+          workerRun
+        }),
+        status: "continue",
+        publication: {
+          kind: "changes",
+          diff: persistenceDiff,
+          candidateChangedIds: preciseChangedIds
+        }
+      };
+    } catch (error) {
+      workerRun.discard();
+      throw error;
     }
-    return this.refreshStrategyResult(sessions, result.completeness, scope, {
-      preciseChangedIds,
-      persistenceDiff,
-      scanDuration: performance.now() - scanStartedAt,
-      sourceFailures: result.sourceFailures ?? []
-    });
   }
-  async refreshChangedAgent(agent, baseline, cacheTimestamp, refreshStartedAt) {
+  async refreshChangedAgent(agent, refresh, baseline, 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") {
+    if (refresh.kind === "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
+        source_path: refresh.failure.sourcePath,
+        error_class: refresh.failure.errorClass,
+        message: refresh.failure.message
       });
-      return this.refreshStrategyResult(
-        baseline,
-        "partial",
-        {},
-        { status: "unchanged", checkDuration }
-      );
-    }
-    if (!checkResult.hasChanges) {
-      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);
-      agent.commitChangeCheck();
-      this.lastRefreshAtByAgent.set(agent.name, checkResult.timestamp);
-      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,
+      return {
+        ...this.refreshStrategyBase(
+          baseline,
+          "partial",
           {},
           {
-            status: "unchanged",
-            checkDuration,
-            scanDuration: performance.now() - scanStartedAt2
+            checkDuration: refresh.checkDurationMs
           }
-        );
-      }
-      return this.refreshStrategyResult(
-        sessions2,
-        result.completeness,
-        {},
-        {
-          persistenceDiff,
-          checkDuration,
-          scanDuration: performance.now() - scanStartedAt2,
-          sourceFailures: result.sourceFailures ?? []
+        ),
+        status: "unchanged"
+      };
+    }
+    const { check: checkResult, source } = refresh;
+    const checkDuration = refresh.checkDurationMs;
+    if (refresh.kind === "recompute-derived") {
+      const scanStartedAt2 = performance.now();
+      const workerRun = await this.runWorker(agent, baseline, { kind: "recompute-derived" }, {});
+      try {
+        const { result } = workerRun;
+        agent.restoreSessionCacheMeta(result.meta);
+        const sessions2 = attachMissingProjectIdentities(result.sessions);
+        this.lastRefreshAtByAgent.set(agent.name, checkResult.timestamp);
+        const persistenceDiff = buildSessionPersistenceDiff(baseline, sessions2);
+        if (persistenceDiff.changedSessions.length === 0 && persistenceDiff.removedSessionIds.length === 0) {
+          this.logUnchangedRefresh(agent.name, refreshStartedAt);
+          return {
+            ...this.refreshStrategyBase(
+              sessions2,
+              result.completeness,
+              {},
+              {
+                checkDuration,
+                scanDuration: performance.now() - scanStartedAt2,
+                workerRun,
+                commitChangeCheck: () => commitAgentRefreshCheck(refresh)
+              }
+            ),
+            status: "unchanged"
+          };
         }
-      );
+        return {
+          ...this.refreshStrategyBase(
+            sessions2,
+            result.completeness,
+            {},
+            {
+              checkDuration,
+              scanDuration: performance.now() - scanStartedAt2,
+              sourceFailures: result.sourceFailures ?? [],
+              workerRun,
+              commitChangeCheck: () => commitAgentRefreshCheck(refresh)
+            }
+          ),
+          status: "continue",
+          publication: { kind: "changes", diff: persistenceDiff, candidateChangedIds: [] }
+        };
+      } catch (error) {
+        workerRun.discard();
+        throw error;
+      }
     }
-    const preciseChangedIds = checkResult.changedIds ?? null;
     const scanStartedAt = performance.now();
-    if (preciseChangedIds === null) {
-      const result = await this.runWorker(agent, baseline, { kind: "full-scan" }, scope);
-      agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
-      const sessions2 = attachMissingProjectIdentities(result.sessions);
-      agent.commitChangeCheck();
-      this.lastRefreshAtByAgent.set(agent.name, checkResult.timestamp);
-      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,
-        sourceFailures: result.sourceFailures ?? []
-      });
+    if (refresh.kind === "full-scan") {
+      const workerRun = await this.runWorker(agent, baseline, { kind: "full-scan" }, scope);
+      try {
+        const { result } = workerRun;
+        agent.restoreSessionCacheMeta(result.meta);
+        const sessions2 = attachMissingProjectIdentities(result.sessions);
+        this.lastRefreshAtByAgent.set(agent.name, checkResult.timestamp);
+        return {
+          ...this.refreshStrategyBase(sessions2, result.completeness, scope, {
+            checkDuration,
+            scanDuration: performance.now() - scanStartedAt,
+            sourceFailures: result.sourceFailures ?? [],
+            workerRun,
+            commitChangeCheck: () => commitAgentRefreshCheck(refresh)
+          }),
+          status: "continue",
+          publication: {
+            kind: "changes",
+            // 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.
+            diff: buildSessionPersistenceDiff(baseline, sessions2, {
+              candidateChangedIds: result.changedIds ?? [],
+              completeness: result.completeness,
+              explicitRemovedSessionIds: result.explicitRemovedSessionIds
+            }),
+            candidateChangedIds: []
+          }
+        };
+      } catch (error) {
+        workerRun.discard();
+        throw error;
+      }
     }
-    this.options.workerRunner.discard?.(agent.name);
+    const preciseChangedIds = refresh.check.changedIds;
+    this.options.workerRunner.reset(agent.name);
     const sessions = attachMissingProjectIdentities(
       await Promise.resolve(
-        agent.incrementalScan(baseline, preciseChangedIds, checkResult.refs, scope)
+        source.incrementalScan(baseline, preciseChangedIds, checkResult.refs, scope)
       )
     );
-    agent.commitChangeCheck();
     this.lastRefreshAtByAgent.set(agent.name, checkResult.timestamp);
     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,
-        completeness,
-        preciseChangedIds
-      ),
-      checkDuration,
-      scanDuration: performance.now() - scanStartedAt,
-      sourceFailures
-    });
-  }
-  async scanAgentFully(agent, previousSessions) {
-    const scanStartedAt = performance.now();
-    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, result.completeness, scope, {
-      fullScanSessions: sessions,
-      explicitRemovedSessionIds: result.explicitRemovedSessionIds,
-      scanDuration: performance.now() - scanStartedAt,
-      sourceFailures: result.sourceFailures ?? []
-    });
-  }
-  refreshStrategyResult(nextSessions, completeness, scope, overrides = {}) {
+    const completeness = resolveSessionSnapshotCompleteness(scope, sourceFailures);
     return {
+      ...this.refreshStrategyBase(sessions, completeness, scope, {
+        checkDuration,
+        scanDuration: performance.now() - scanStartedAt,
+        sourceFailures,
+        commitChangeCheck: () => commitAgentRefreshCheck(refresh)
+      }),
       status: "continue",
+      publication: {
+        kind: "changes",
+        diff: buildSessionPersistenceDiff(baseline, sessions, {
+          candidateChangedIds: preciseChangedIds,
+          completeness,
+          explicitRemovedSessionIds: preciseChangedIds
+        }),
+        candidateChangedIds: preciseChangedIds
+      }
+    };
+  }
+  refreshStrategyBase(nextSessions, completeness, scope, overrides = {}) {
+    return {
       nextSessions,
-      fullScanSessions: null,
-      preciseChangedIds: null,
-      persistenceDiff: null,
       checkDuration: 0,
       scanDuration: 0,
       sourceFailures: [],
       completeness,
       scope,
-      explicitRemovedSessionIds: [],
       ...overrides
     };
   }
@@ -4222,85 +5290,8 @@ var AgentSyncEngine = class {
     }
     return outcome.value;
   }
-  needsBackfill(agent, cached, reloadCached = false) {
-    const startupScanOptions = this.startupScanOptions();
-    if (startupScanOptions.from == null && startupScanOptions.to == null) return false;
-    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 (!agent.isAvailable()) return false;
-    let cachedSessions = cached;
-    if (reloadCached || cached === void 0) {
-      const outcome = readCachedSessions(agent.name);
-      if (outcome.status === "failed") {
-        appLogger.warn("scan.backfill.cache_state_unavailable", {
-          agent: agent.name,
-          state: "cached_sessions"
-        });
-        return false;
-      }
-      cachedSessions = outcome.value;
-    }
-    const sourceCount = agent.listSessionSources().length;
-    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,
-        cached_sessions: cachedCount,
-        source_files: sourceCount,
-        last_sync_at: lastSyncAt
-      });
-      return true;
-    }
-    return false;
-  }
   enqueueBackfill(agentName) {
-    if (this.isShuttingDown || !this.backfills.enqueue(agentName)) return;
-    this.statusReporter.publishBackfillStatus();
-    this.pumpBackfillQueue();
-  }
-  pumpBackfillQueue() {
-    if (this.isShuttingDown) return;
-    const attempt = this.backfills.startNext();
-    if (!attempt) return;
-    this.statusReporter.publishBackfillStatus();
-    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.statusReporter.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.statusReporter.publishBackfillStatus();
-      }
-    }
-    this.pumpBackfillQueue();
-  }
-  rejectBackfillAttempt(attempt, error) {
-    appLogger.error("scan.backfill.queue_error", { agent: attempt.agentName, error });
-    this.completeBackfillAttempt(attempt, "failed");
+    this.backfillScheduler.enqueue(agentName);
   }
   runBackfill(attempt) {
     return this.scheduler.run(attempt.agentName, "backfill", () => this.performBackfill(attempt));
@@ -4315,8 +5306,8 @@ var AgentSyncEngine = class {
     const baseline = cached?.sessions ?? snapshot.byAgent[agentName] ?? [];
     const meta = cached?.meta ?? buildAgentCacheMeta(agent);
     const backfillCursor = getAgentFullSyncCursor(agentName);
-    if (cached) restoreAgentCacheMeta(agent, cached);
-    let durableCommitted = false;
+    if (cached) agent.restoreSessionCacheMeta(cached.meta);
+    let workerRun;
     try {
       if (!markAgentFullSyncStarted(agentName)) {
         appLogger.warn("scan.backfill.cache_state_unavailable", {
@@ -4324,13 +5315,17 @@ var AgentSyncEngine = class {
           state: "full_sync_started"
         });
       }
-      const operation = agent instanceof FileSystemSessionSource ? { kind: "source-backfill", cursor: backfillCursor, checkpoint: "durable" } : { kind: "full-backfill", cursor: backfillCursor, checkpoint: "durable" };
+      const operation = {
+        kind: "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(
+      workerRun = await this.runWorker(
         agent,
         baseline,
         operation,
@@ -4341,7 +5336,8 @@ var AgentSyncEngine = class {
           onCheckpoint: (checkpoint) => this.handleBackfillCheckpoint(agentName, checkpoint)
         }
       );
-      agent.setSessionMetaMap(new Map(Object.entries(result.meta)));
+      const { result } = workerRun;
+      agent.restoreSessionCacheMeta(result.meta);
       const fullSessions = attachMissingProjectIdentities(result.sessions);
       const completion = buildScanCompletion(result.completeness, result.sourceFailures ?? []);
       this.statusReporter.flushProgressStatus(`backfill:${agentName}`);
@@ -4354,7 +5350,7 @@ var AgentSyncEngine = class {
         }
       };
       updatePublicationPhase("publish-queued");
-      const publication = await this.commitSessionPublication({
+      await this.sessionPublication.commit({
         context: "scan.backfill",
         agentName,
         sessions: fullSessions,
@@ -4369,81 +5365,50 @@ var AgentSyncEngine = class {
           removedSessionIds: result.explicitRemovedSessionIds,
           saveCache: true
         },
+        stagedRun: workerRun,
         onPublishing: () => updatePublicationPhase("publishing"),
+        onPublicationProgress: ({ stage }) => {
+          if (stage === "prepared") updatePublicationPhase("indexing");
+          if (stage === "search_staged") updatePublicationPhase("committing");
+        },
         onCommitted: () => {
-          durableCommitted = true;
           if (completion.completeness === "partial") {
             this.backfills.recordCompletion(attempt, completion);
           }
         }
       });
-      durableCommitted = publication.durableCommitted;
-      this.options.workerRunner.commit?.(agentName);
-      if (!markAgentFullSyncCompleted(agentName)) {
-        appLogger.warn("scan.backfill.completion_not_durable", { agent: agentName });
-      }
-      appLogger.info(
-        result.sourceFailures?.length ? "scan.backfill.partial" : "scan.backfill.done",
-        {
-          agent: agentName,
-          duration_ms: Math.round(performance.now() - startedAt),
-          sessions: fullSessions.length,
-          changed: result.changedIds?.length ?? 0,
-          failed_sources: result.sourceFailures?.length ?? 0
+      try {
+        if (completion.completeness === "complete" && !markAgentFullSyncCompleted(agentName)) {
+          appLogger.warn("scan.backfill.completion_not_durable", { agent: agentName });
         }
-      );
-      if (result.sourceFailures?.length) {
-        appLogger.warn("scan.backfill.source_failures", {
-          agent: agentName,
-          failures: result.sourceFailures
-        });
+        appLogger.info(
+          completion.completeness === "partial" ? "scan.backfill.partial" : "scan.backfill.done",
+          {
+            agent: agentName,
+            duration_ms: Math.round(performance.now() - startedAt),
+            sessions: fullSessions.length,
+            changed: result.changedIds?.length ?? 0,
+            failed_sources: result.sourceFailures?.length ?? 0
+          }
+        );
+        if (result.sourceFailures?.length) {
+          appLogger.warn("scan.backfill.source_failures", {
+            agent: agentName,
+            failures: result.sourceFailures
+          });
+        }
+      } catch (error) {
+        this.reportPostCommitError("scan.backfill", agentName, error);
       }
       return "committed";
     } catch (error) {
-      if (durableCommitted) {
-        this.reportPostCommitError("scan.backfill", agentName, error);
-        return "committed";
-      }
-      agent.setSessionMetaMap(new Map(Object.entries(meta)));
-      this.options.workerRunner.discard?.(agentName);
+      agent.restoreSessionCacheMeta(meta);
+      workerRun?.discard();
       appLogger.error("scan.backfill.error", { agent: agentName, error });
       console.error(`[${agentName}] Backfill failed:`, error);
       return "failed";
     }
   }
-  async commitSessionPublication(publication) {
-    const publicationId = this.indexPublisher.publicationId(
-      publication.context,
-      publication.agentName
-    );
-    await this.indexPublisher.commitSearchIndex(publication.context, [publication.indexJob], {
-      publicationId,
-      agent: publication.agentName,
-      ...publication.onPublishing ? { onStarted: publication.onPublishing } : {}
-    });
-    const diffStartedAt = performance.now();
-    const event = this.sessionIndex.commitAgentSessions(
-      publication.agentName,
-      publication.sessions,
-      publication.candidateChangedIds
-    );
-    const diffDuration = performance.now() - diffStartedAt;
-    const result = { durableCommitted: true, event, diffDuration };
-    publication.onCommitted?.(result);
-    this.emitSessionsChanged({
-      agentName: publication.agentName,
-      sessions: this.sessionIndex.snapshot().byAgent[publication.agentName] ?? [],
-      event
-    });
-    appLogger.info("session.publication.published", {
-      publication_id: publicationId,
-      context: publication.context,
-      agent: publication.agentName,
-      sessions: publication.sessions.length,
-      has_event: event != null
-    });
-    return result;
-  }
   findAgent(agentName) {
     return this.sessionIndex.findAgent(agentName);
   }
@@ -4460,7 +5425,7 @@ var AgentSyncEngine = class {
 
 // src/session-watcher.ts
 import { existsSync as existsSync3, readdirSync, statSync, watch } from "fs";
-import { dirname as dirname2, isAbsolute, join, relative, resolve as resolve2 } from "path";
+import { dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "path";
 var WRITE_STABILITY_THRESHOLD_MS = 250;
 var WRITE_STABILITY_POLL_MS = 100;
 function toAbsolutePath(path) {
@@ -4484,11 +5449,11 @@ function getWatchRoot(path) {
   const stat = statSync(path);
   return stat.isDirectory() ? path : dirname2(path);
 }
-function isRecursiveWatchSupported(platform = process.platform, nodeVersion = process.versions.node) {
-  if (platform === "darwin" || platform === "win32") {
+function isRecursiveWatchSupported(platform2 = process.platform, nodeVersion = process.versions.node) {
+  if (platform2 === "darwin" || platform2 === "win32") {
     return true;
   }
-  if (platform !== "linux" && platform !== "aix" && platform !== "ibmi") {
+  if (platform2 !== "linux" && platform2 !== "aix" && platform2 !== "ibmi") {
     return false;
   }
   const [major = 0, minor = 0] = nodeVersion.split(".").map((part) => Number(part));
@@ -4522,7 +5487,7 @@ function resolveWatchEventPath(watchPath, filename) {
   if (!filenameText) {
     return watchPath;
   }
-  return isAbsolute(filenameText) ? filenameText : join(watchPath, filenameText);
+  return isAbsolute(filenameText) ? filenameText : join2(watchPath, filenameText);
 }
 var SessionWatcher = class {
   watchers = [];
@@ -4640,7 +5605,7 @@ var SessionWatcher = class {
       try {
         for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
           if (entry.isDirectory()) {
-            pending.push(join(dirPath, entry.name));
+            pending.push(join2(dirPath, entry.name));
           }
         }
       } catch (error) {
@@ -4768,8 +5733,10 @@ var SHUTDOWN_ERROR_MESSAGE3 = "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));
+  for (const { session } of changes) replacedIds.add(session.reference.sessionId);
+  const retained = previousSessions.filter(
+    (session) => !replacedIds.has(session.reference.sessionId)
+  );
   const next = Array.from({
     length: retained.length + changes.length
   });
@@ -4857,24 +5824,7 @@ var ThreadWorkerRunner = class {
       }
     });
   }
-  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) {
+  reset(agentName) {
     const slot = this.workers.get(agentName);
     if (slot) this.invalidateWorker(agentName, slot);
   }
@@ -4900,7 +5850,6 @@ var ThreadWorkerRunner = class {
       awaitingCommit: null,
       closed: false
     };
-    worker.unref();
     this.workers.set(agentName, slot);
     worker.on("message", (message) => {
       if (appLogger.consumeWorkerMessage(message)) return;
@@ -4953,7 +5902,7 @@ var ThreadWorkerRunner = class {
       this.invalidateWorker(slot.agentName, slot);
       return;
     }
-    const changedIds = message.changes.map(({ session }) => session.id);
+    const changedIds = message.changes.map(({ session }) => session.reference.sessionId);
     const replacedSessionIds = [...changedIds, ...message.removedSessionIds];
     const removedMetaIds = [...message.removedSessionIds, ...message.removedMetaIds];
     try {
@@ -4973,12 +5922,52 @@ var ThreadWorkerRunner = class {
         requestId: message.requestId,
         generation: message.generation
       };
-      pending.resolve(result);
+      pending.resolve(this.createStagedRun(slot, message.requestId, message.generation, result));
     } catch (error) {
       pending.reject(toError2(error));
       this.invalidateWorker(slot.agentName, slot);
     }
   }
+  createStagedRun(slot, requestId, generation, result) {
+    let finalized = false;
+    return {
+      result,
+      commit: () => {
+        if (finalized) return;
+        finalized = true;
+        this.commitStagedRun(slot, requestId, generation);
+      },
+      discard: () => {
+        if (finalized) return;
+        finalized = true;
+        this.discardStagedRun(slot, requestId, generation);
+      }
+    };
+  }
+  commitStagedRun(slot, requestId, generation) {
+    const awaiting = slot.awaitingCommit;
+    if (this.workers.get(slot.agentName) !== slot || awaiting?.requestId !== requestId || awaiting.generation !== generation) {
+      return;
+    }
+    const request = {
+      type: "commit",
+      requestId,
+      generation
+    };
+    try {
+      slot.worker.postMessage(request);
+      slot.awaitingCommit = null;
+      slot.generation += 1;
+    } catch {
+      this.invalidateWorker(slot.agentName, slot);
+    }
+  }
+  discardStagedRun(slot, requestId, generation) {
+    const awaiting = slot.awaitingCommit;
+    if (this.workers.get(slot.agentName) === slot && awaiting?.requestId === requestId && awaiting.generation === generation) {
+      this.invalidateWorker(slot.agentName, slot);
+    }
+  }
   closeWorker(agentName, slot, error) {
     if (slot.closed) return;
     slot.closed = true;
@@ -5038,7 +6027,6 @@ var LiveScanStore = class {
     const initialResult = await scanSessions({
       ...this.scanOptions,
       useCache: this.scanOptions.useCache ?? true,
-      smartRefresh: false,
       cacheOnly: this.deferInitialRefresh,
       writeCache: this.deferInitialRefresh ? false : this.scanOptions.writeCache,
       smartTagWorkerUrl: this.getSmartTagWorkerUrl() ?? void 0,
@@ -5074,7 +6062,13 @@ var LiveScanStore = class {
             check_changes_ms: timing.checkChanges != null ? Math.round(timing.checkChanges) : void 0,
             scan_ms: timing.scan != null ? Math.round(timing.scan) : void 0,
             identity_ms: timing.identity != null ? Math.round(timing.identity) : void 0,
-            tags_ms: timing.tags != null ? Math.round(timing.tags) : void 0
+            tags_ms: timing.tags != null ? Math.round(timing.tags) : void 0,
+            source_enumeration_ms: timing.sourceEnumeration != null ? Math.round(timing.sourceEnumeration) : void 0,
+            source_diff_ms: timing.sourceDiff != null ? Math.round(timing.sourceDiff) : void 0,
+            source_parse_ms: timing.sourceParse != null ? Math.round(timing.sourceParse) : void 0,
+            enumerated_sources: timing.enumeratedSources,
+            changed_sources: timing.changedSources,
+            processed_sources: timing.processedSources
           }
         ])
       ) : void 0
@@ -5120,7 +6114,7 @@ var LiveScanStore = class {
   }
   emit(event) {
     if (this.shuttingDown) return;
-    if (this.pendingEvent || event.newSessions > 0) {
+    if (this.pendingEvent || event.newSessionRefs.length > 0) {
       this.queueEvent(event);
       return;
     }
@@ -5195,7 +6189,7 @@ function formatScanFailureDiagnostics(snapshot) {
 }
 function formatCacheFailureDiagnostics(snapshot) {
   return Object.values(snapshot.cacheFailures ?? {}).map(
-    (failure) => `[${failure.agentName}] Cache persistence failed; serving in-memory results without advancing the durable baseline`
+    (failure) => failure.operation === "read" ? `[${failure.agentName}] Cache read failed; durable baseline is unavailable` : `[${failure.agentName}] Cache persistence failed; serving in-memory results without advancing the durable baseline`
   );
 }
 function buildSessionIndexOutput(snapshot, window = {}) {
@@ -5331,6 +6325,10 @@ var main = defineCommand({
       description: "A reverse proxy in front of CodeSesh terminates TLS",
       default: false
     },
+    "public-url": {
+      type: "string",
+      description: "Public HTTPS origin served by the trusted reverse proxy"
+    },
     agent: {
       type: "string",
       alias: "a",
@@ -5398,6 +6396,7 @@ var main = defineCommand({
     const hostname = args.host;
     const remoteAccess = args["remote-access"];
     let transport;
+    let publicOrigin;
     try {
       transport = resolveRemoteTransport({
         hostname,
@@ -5405,13 +6404,14 @@ var main = defineCommand({
         tlsKeyPath: args["tls-key"],
         trustProxy: args["trust-proxy"]
       });
+      publicOrigin = resolvePublicOrigin(args["public-url"], transport);
     } catch (error) {
       console.error(error instanceof Error ? error.message : String(error));
       process.exit(1);
     }
-    if (resolveRemoteAccessPolicy(hostname, transport).authenticationRequired && !remoteAccess) {
+    if (resolveRemoteAccessPolicy(hostname, transport).remoteAccessRequired && !remoteAccess) {
       console.error(
-        `Refusing to expose CodeSesh on ${hostname} without authentication. Add --remote-access to continue.`
+        `Refusing to expose CodeSesh on ${hostname} without explicit remote access. Add --remote-access to continue.`
       );
       process.exit(1);
     }
@@ -5423,6 +6423,7 @@ var main = defineCommand({
       port,
       host: hostname,
       transport: transport.kind,
+      public_url: publicOrigin,
       remote_access: remoteAccess,
       json: jsonOnly,
       no_open: noOpen,
@@ -5432,7 +6433,7 @@ var main = defineCommand({
       log_path: appLogger.getLogPath()
     });
     if (clearCache) {
-      const { clearCache: clear } = await import("./dist-RHDY2EZX.js");
+      const { clearCache: clear } = await import("./discovery-K3GLISI6.js");
       clear();
       appLogger.info("cache.clear");
       console.log("Cache cleared.");
@@ -5484,18 +6485,21 @@ var main = defineCommand({
       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;
+      } else {
+        for (const diagnostic of formatCacheFailureDiagnostics(result)) console.error(diagnostic);
+        const output = buildSessionIndexOutput(result, {
+          from: listDefaultFrom,
+          to: listDefaultTo
+        });
+        appLogger.info("cli.json_output", {
+          sessions: output.sessions.length,
+          duration_ms: Math.round(performance.now() - startedAt)
+        });
+        console.log(JSON.stringify(output, null, 2));
       }
-      for (const diagnostic of formatCacheFailureDiagnostics(result)) console.error(diagnostic);
-      const output = buildSessionIndexOutput(result, { from: listDefaultFrom, to: listDefaultTo });
-      appLogger.info("cli.json_output", {
-        sessions: output.sessions.length,
-        duration_ms: Math.round(performance.now() - startedAt)
-      });
-      console.log(JSON.stringify(output, null, 2));
+      await store.shutdown();
       return;
     }
     const agents = createRegisteredAgents();
@@ -5509,7 +6513,8 @@ var main = defineCommand({
         portFallbackAttempts: explicitPort ? 1 : DEFAULT_PORT_FALLBACK_ATTEMPTS,
         hostname,
         remoteAccess,
-        transport
+        transport,
+        publicUrl: publicOrigin
       });
     } catch (error) {
       console.error(getServerStartupErrorMessage(error, port));