fix(ai): show live reindex progress in semantic-search settings

The "Indexed X of Y pages" counter stayed stuck at "478 of 478" during a
manual "Reindex now" run instead of resetting to 0 and climbing. The status
reports indexedPages = countIndexedPages (DISTINCT pages with >=1 embedding
row), but reindex hard-replaces each page in its OWN small transaction, so
nearly all pages always have rows -> the count never drops.

Add a per-workspace live reindex-progress record in Redis (reusing the
existing global ioredis client via RedisService, no new Redis config):
- EmbeddingReindexProgressService: start/increment/clear/get over a Redis hash
  with a 1h TTL self-clean; all best-effort/cosmetic so a Redis failure degrades
  to the existing DB-count behavior.
- AiSettingsService.reindex seeds {total, done:0, startedAt} at enqueue time so
  the very first poll already reports done=0.
- EmbeddingIndexerService.reindexWorkspace overwrites total with the real page
  count at start, increments done per processed page (success or handled
  failure), and clears the record in a finally (covers success, fatal abort,
  and the unconfigured early-return) so a failed run never sticks.
- AiSettingsService.getMasked returns the live run numbers when a progress
  record is active (plus an optional reindexing flag), else falls back to
  countIndexedPages/countEmbeddablePages.

Per-page edits (reindexPage) never touch the workspace progress record, and no
mass up-front delete is introduced (search availability preserved).

Tests: indexer sets/increments/clears progress (incl. fatal abort and
unconfigured early-return); status reports run progress when active and falls
back when not.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/server/src/integrations/ai/ai-settings.service.spec.ts

@@ -1,4 +1,12 @@
-import { parsePositiveInt } from './ai-settings.service';
+import { AiSettingsService, parsePositiveInt } from './ai-settings.service';
+import { WorkspaceRepo } from '@docmost/db/repos/workspace/workspace.repo';
+import { AiAgentRoleRepo } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
+import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider-credentials.repo';
+import { PageEmbeddingRepo } from '@docmost/db/repos/ai-chat/page-embedding.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { SecretBoxService } from '../crypto/secret-box';
+import { EmbeddingReindexProgressService } from './embedding-reindex-progress.service';
+import type { Queue } from 'bullmq';
 
 /**
  * Round-trip coercion for numeric `::text` provider settings (e.g.
@@ -41,3 +49,74 @@ describe('parsePositiveInt', () => {
     expect(parsePositiveInt(42)).toBe(42);
   });
 });
+
+/**
+ * getMasked must surface the LIVE reindex run progress while a reindex is active
+ * (so the "Indexed X of Y" counter can climb 0 -> total), and fall back to the
+ * steady-state DB coverage count (countIndexedPages / countEmbeddablePages) when
+ * no reindex is running. This is the server side of the fix for the counter that
+ * otherwise stays stuck at "478 of 478" the whole reindex.
+ */
+describe('AiSettingsService.getMasked reindex progress', () => {
+  const WORKSPACE_ID = 'ws-1';
+
+  function makeService() {
+    // No driver configured -> the credentials lookup is skipped, keeping the
+    // setup minimal; we only care about the indexed/total numbers here.
+    const workspaceRepo = {
+      findById: jest.fn().mockResolvedValue({ settings: {} }),
+    };
+    const aiAgentRoleRepo = {};
+    const aiProviderCredentialsRepo = { find: jest.fn() };
+    const pageEmbeddingRepo = {
+      countIndexedPages: jest.fn().mockResolvedValue(478),
+    };
+    const pageRepo = {
+      countEmbeddablePages: jest.fn().mockResolvedValue(478),
+    };
+    const secretBox = {};
+    const reindexProgress = {
+      get: jest.fn().mockResolvedValue(null),
+    };
+    const aiQueue = {};
+
+    const service = new AiSettingsService(
+      workspaceRepo as unknown as WorkspaceRepo,
+      aiAgentRoleRepo as unknown as AiAgentRoleRepo,
+      aiProviderCredentialsRepo as unknown as AiProviderCredentialsRepo,
+      pageEmbeddingRepo as unknown as PageEmbeddingRepo,
+      pageRepo as unknown as PageRepo,
+      secretBox as unknown as SecretBoxService,
+      reindexProgress as unknown as EmbeddingReindexProgressService,
+      aiQueue as unknown as Queue,
+    );
+    return { service, reindexProgress, pageEmbeddingRepo };
+  }
+
+  it('reports the live run numbers when a reindex progress record is active', async () => {
+    const { service, reindexProgress } = makeService();
+    // Mid-run: 120 of 478 pages processed.
+    reindexProgress.get.mockResolvedValue({
+      total: 478,
+      done: 120,
+      startedAt: Date.now(),
+    });
+
+    const masked = await service.getMasked(WORKSPACE_ID);
+
+    expect(masked.indexedPages).toBe(120);
+    expect(masked.totalPages).toBe(478);
+    expect(masked.reindexing).toBe(true);
+  });
+
+  it('falls back to countIndexedPages when no reindex is active', async () => {
+    const { service, reindexProgress } = makeService();
+    reindexProgress.get.mockResolvedValue(null);
+
+    const masked = await service.getMasked(WORKSPACE_ID);
+
+    expect(masked.indexedPages).toBe(478);
+    expect(masked.totalPages).toBe(478);
+    expect(masked.reindexing).toBe(false);
+  });
+});

apps/server/src/integrations/ai/ai-settings.service.ts

@@ -8,6 +8,7 @@ import { AiProviderCredentialsRepo } from '@docmost/db/repos/ai-chat/ai-provider
 import { PageEmbeddingRepo } from '@docmost/db/repos/ai-chat/page-embedding.repo';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { SecretBoxService } from '../crypto/secret-box';
+import { EmbeddingReindexProgressService } from './embedding-reindex-progress.service';
 import {
   AiDriver,
   AiProviderSettings,
@@ -74,6 +75,7 @@ export class AiSettingsService {
     private readonly pageEmbeddingRepo: PageEmbeddingRepo,
     private readonly pageRepo: PageRepo,
     private readonly secretBox: SecretBoxService,
+    private readonly reindexProgress: EmbeddingReindexProgressService,
     @InjectQueue(QueueName.AI_QUEUE) private readonly aiQueue: Queue,
   ) {}
 
@@ -100,6 +102,15 @@ export class AiSettingsService {
       .remove(`ai-search-disabled-${workspaceId}`)
       .catch(() => undefined);
 
+    // Seed a live progress record BEFORE enqueueing so the very first status
+    // poll already reports done=0 (the reindex POST returns the PRE-job counts,
+    // so without this seed the first poll would still show "total of total").
+    // The worker overwrites `total` with the real page count, increments `done`
+    // as it runs, and clears the record in a finally. `totalPages` uses the same
+    // source the status endpoint reports, so the counter denominator matches.
+    const totalPages = await this.pageRepo.countEmbeddablePages(workspaceId);
+    await this.reindexProgress.start(workspaceId, totalPages);
+
     const jobId = `ai-reindex-${workspaceId}`;
     // Clear a prior non-active entry so a stale job can't block this reindex.
     // A locked/active job is left in place (remove() no-ops) and the add() below
@@ -261,6 +272,15 @@ export class AiSettingsService {
       this.pageRepo.countEmbeddablePages(workspaceId),
     ]);
 
+    // While a reindex run is active, report its LIVE progress (done climbs 0 ->
+    // total) so the settings UI can watch it advance. Without this the counter
+    // never drops: the per-page reindex hard-replaces rows in its own small
+    // transaction, so countIndexedPages stays ~= total for the whole run. With
+    // no active record we fall back to the steady-state DB coverage count, which
+    // preserves the existing display and the client's "done == total -> stop
+    // polling" condition (the run ends -> record cleared -> DB count == total).
+    const progress = await this.reindexProgress.get(workspaceId);
+
     return {
       driver: provider.driver,
       chatModel: provider.chatModel,
@@ -279,8 +299,10 @@ export class AiSettingsService {
       hasApiKey,
       hasEmbeddingApiKey,
       hasSttApiKey,
-      indexedPages,
-      totalPages,
+      indexedPages: progress ? progress.done : indexedPages,
+      totalPages: progress ? progress.total : totalPages,
+      // Optional hint for the client: a reindex run is currently in progress.
+      reindexing: progress != null,
     };
   }
 

apps/server/src/integrations/ai/ai.module.ts

@@ -5,6 +5,7 @@ import { QueueName } from '../queue/constants';
 import { AiService } from './ai.service';
 import { AiSettingsService } from './ai-settings.service';
 import { AiSettingsController } from './ai-settings.controller';
+import { EmbeddingReindexProgressService } from './embedding-reindex-progress.service';
 
 /**
  * LLM driver + provider-settings unit (§6.2/§6.4).
@@ -19,7 +20,7 @@ import { AiSettingsController } from './ai-settings.controller';
     BullModule.registerQueue({ name: QueueName.AI_QUEUE }),
   ],
   controllers: [AiSettingsController],
-  providers: [AiService, AiSettingsService],
-  exports: [AiService, AiSettingsService],
+  providers: [AiService, AiSettingsService, EmbeddingReindexProgressService],
+  exports: [AiService, AiSettingsService, EmbeddingReindexProgressService],
 })
 export class AiModule {}

apps/server/src/integrations/ai/ai.types.ts

@@ -146,4 +146,7 @@ export interface MaskedAiSettings {
   // RAG indexing coverage for the settings UI.
   indexedPages: number;
   totalPages: number;
+  // True while a full workspace reindex is actively running (the counts above
+  // then reflect the live run progress rather than the steady-state DB count).
+  reindexing?: boolean;
 }

apps/server/src/integrations/ai/embedding-reindex-progress.service.ts

@@ -0,0 +1,143 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { RedisService } from '@nestjs-labs/nestjs-ioredis';
+import type { Redis } from 'ioredis';
+
+/**
+ * Live progress of an in-flight workspace embeddings reindex run.
+ * `total` is the number of pages the run will process, `done` how many it has
+ * already processed (success OR handled failure), `startedAt` the epoch-ms the
+ * record was created.
+ */
+export interface ReindexProgress {
+  total: number;
+  done: number;
+  startedAt: number;
+}
+
+/** Redis key namespace for the per-workspace reindex-progress record. */
+const KEY_PREFIX = 'ai:reindex:progress:';
+
+/**
+ * TTL (seconds) on the progress record so a crashed/aborted worker that never
+ * reaches its `clear()` finally can still self-clean instead of leaving a stuck
+ * "reindexing" state. Refreshed on every increment so a long run never expires
+ * mid-flight; on a crash it disappears within TTL of the last processed page.
+ */
+const TTL_SECONDS = 60 * 60; // 1h
+
+/**
+ * Cluster-wide store for the live progress of a workspace embeddings reindex.
+ *
+ * The reindex runs in a BullMQ worker (AI_QUEUE) that may be a DIFFERENT process
+ * than the API handling the settings-status GET, so the progress must live in
+ * the shared Redis — we reuse the same global ioredis client (RedisService from
+ * @nestjs-labs/nestjs-ioredis) that backs BullMQ and the other anti-abuse
+ * limiters, adding NO new Redis config.
+ *
+ * Everything here is best-effort and COSMETIC: progress only drives the "Indexed
+ * X of Y" counter while a reindex is running. Any Redis failure degrades to the
+ * existing steady-state behaviour (the status falls back to the DB coverage
+ * count), so reads fail to `null` and writes are swallowed — a reindex must
+ * never break because progress reporting did.
+ *
+ * Stored as a Redis HASH so `done` can be bumped with an atomic HINCRBY (the
+ * worker is the only writer of `done`, but HINCRBY also keeps us off a
+ * read-modify-write race and preserves the other fields).
+ */
+@Injectable()
+export class EmbeddingReindexProgressService {
+  private readonly logger = new Logger(EmbeddingReindexProgressService.name);
+  private readonly redis: Redis;
+
+  constructor(redisService: RedisService) {
+    this.redis = redisService.getOrThrow();
+  }
+
+  private key(workspaceId: string): string {
+    return KEY_PREFIX + workspaceId;
+  }
+
+  /**
+   * Begin (or reset) the progress record for a workspace: `total` pages, `done`
+   * back to 0, `startedAt` now. Called at reindex enqueue time (placeholder
+   * total, so the very first status poll already reports done=0) and again at
+   * the worker start (overwriting `total` with the real page count). Resets
+   * `done` to 0 so a re-trigger never inherits a stale count.
+   */
+  async start(workspaceId: string, total: number): Promise<void> {
+    const key = this.key(workspaceId);
+    try {
+      await this.redis
+        .multi()
+        .hset(key, {
+          total: String(total),
+          done: '0',
+          startedAt: String(Date.now()),
+        })
+        .expire(key, TTL_SECONDS)
+        .exec();
+    } catch (err) {
+      this.logger.warn(
+        `reindex-progress start failed for workspace ${workspaceId}; ` +
+          `progress reporting disabled for this run: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  /**
+   * Bump the processed-page counter by one and refresh the TTL. Atomic and
+   * best-effort: a missing key (cleared/expired) would be recreated with only
+   * `done`, but `get()` treats a record without a numeric `total` as inactive,
+   * so that partial state safely reads as "no active reindex".
+   */
+  async increment(workspaceId: string): Promise<void> {
+    const key = this.key(workspaceId);
+    try {
+      await this.redis.multi().hincrby(key, 'done', 1).expire(key, TTL_SECONDS).exec();
+    } catch (err) {
+      this.logger.warn(
+        `reindex-progress increment failed for workspace ${workspaceId}: ` +
+          `${(err as Error).message}`,
+      );
+    }
+  }
+
+  /**
+   * Remove the progress record. Called in the worker's `finally` so a completed,
+   * aborted, or unconfigured-early-return run never leaves a stuck record; the
+   * status then falls back to the DB coverage count.
+   */
+  async clear(workspaceId: string): Promise<void> {
+    try {
+      await this.redis.del(this.key(workspaceId));
+    } catch (err) {
+      this.logger.warn(
+        `reindex-progress clear failed for workspace ${workspaceId} ` +
+          `(self-cleans via TTL): ${(err as Error).message}`,
+      );
+    }
+  }
+
+  /**
+   * Read the live progress, or `null` when no reindex is active (no record, an
+   * expired record, or a partial record without a numeric `total`). On a Redis
+   * error returns `null` so the status endpoint degrades to its DB count.
+   */
+  async get(workspaceId: string): Promise<ReindexProgress | null> {
+    try {
+      const data = await this.redis.hgetall(this.key(workspaceId));
+      if (!data || data.total === undefined) return null;
+      const total = Number(data.total);
+      const done = Number(data.done);
+      const startedAt = Number(data.startedAt);
+      if (!Number.isFinite(total) || !Number.isFinite(done)) return null;
+      return { total, done, startedAt: Number.isFinite(startedAt) ? startedAt : 0 };
+    } catch (err) {
+      this.logger.warn(
+        `reindex-progress read failed for workspace ${workspaceId}; ` +
+          `falling back to DB count: ${(err as Error).message}`,
+      );
+      return null;
+    }
+  }
+}