memorix 1.2.7 → 1.2.8

package/docs/dev-log/progress.txt

@@ -339,3 +339,28 @@
   isolated Claude Code handoff/continuation smoke. `npm publish --dry-run
   --ignore-scripts` accepted the public 1.2.7 tarball; the full prepublish
   build/test path is covered by the root release gates above.
+
+## 1.2.8 Vector Recovery and Codex Installation Clarity
+- Reworked vector backfill failure handling so transient provider or local
+  index failures leave one durable, diagnosable retry with bounded backoff
+  instead of consuming the maintenance retry budget in each new MCP process.
+  Healthy work clears stale diagnostics, revives an old failed vector job when
+  needed, and resolves superseded historical failure rows once recovery is
+  complete. Provider calls are batched while process-local Orama writes remain
+  serialized.
+- Corrected dashboard and HTTP control-plane vector reporting. A process that
+  does not own a hydrated MCP search index now states that vector status belongs
+  to the active MCP session rather than showing a misleading green `0 / 0`.
+- Corrected Codex install diagnostics: an enabled official Codex plugin owns
+  its `.mcp.json` `memorix serve` endpoint, while first-use hook approval is an
+  explicit host consent step rather than a broken installation. Plugin setup
+  removes only the legacy source-path `memorix` entry after successful plugin
+  installation; custom user-managed MCP entries are preserved.
+- Release verification: focused regression tests (96 assertions), `npm run
+  lint`, production build, and the full root test suite (all passed, 280s).
+  A live OpenRouter `qwen/qwen3-embedding-8b` batch returned two 4096d vectors.
+  An isolated tarball install reported CLI version `1.2.8`; its stdio MCP
+  handshake exposed 44 tools and completed `memorix_project_context`, and its
+  CLI `context --json` path returned a structured Workset. `npm pack --dry-run`
+  and `npm publish --dry-run --ignore-scripts` both accepted the final tarball
+  without manifest normalization warnings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -11,8 +11,8 @@
     "packages/memcode"
   ],
   "bin": {
-    "memorix": "./dist/cli/index.js",
-    "memcode": "./dist/cli/memcode.js"
+    "memorix": "dist/cli/index.js",
+    "memcode": "dist/cli/memcode.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/src/cli/commands/agent-integrations.ts

@@ -26,6 +26,8 @@ export interface AgentMcpCheck {
   exists: boolean;
   status: AgentIntegrationStatus;
   issues: string[];
+  /** This endpoint is supplied by an enabled Codex plugin, not config.toml. */
+  managedByPlugin?: boolean;
   server?: {
     transport: 'stdio' | 'http';
     command?: string;
@@ -229,6 +231,10 @@ function codexPluginPath(): string {
   return `${homedir()}/.codex/plugins/${CODEX_PLUGIN_NAME}`;
 }
 
+function codexPluginMcpPath(): string {
+  return `${codexPluginPath()}/.mcp.json`;
+}
+
 function codexMarketplacePath(): string {
   return `${homedir()}/.agents/plugins/marketplace.json`;
 }
@@ -267,6 +273,7 @@ async function inspectCodexPluginBundle(): Promise<AgentPluginCheck> {
   const pluginPath = codexPluginPath();
   const manifestPath = `${pluginPath}/.codex-plugin/plugin.json`;
   const hooksPath = `${pluginPath}/hooks/hooks.json`;
+  const mcpPath = codexPluginMcpPath();
   if (!existsSync(pluginPath)) {
     return {
       scope: 'global',
@@ -317,6 +324,20 @@ async function inspectCodexPluginBundle(): Promise<AgentPluginCheck> {
   if (version !== getCliVersion()) issues.push('codex-plugin-version-mismatch');
   if (manifest.hooks !== './hooks/hooks.json') issues.push('codex-hook-manifest-missing');
 
+  if (!existsSync(mcpPath)) {
+    issues.push('codex-plugin-mcp-manifest-missing');
+  } else {
+    try {
+      const mcpConfig = asRecord(JSON.parse(await readFile(mcpPath, 'utf-8')));
+      const server = coerceMcpServer('memorix', asRecord(mcpConfig?.mcpServers)?.memorix);
+      if (!server || !isRecommendedStdioServer(server)) {
+        issues.push('codex-plugin-mcp-manifest-invalid');
+      }
+    } catch {
+      issues.push('codex-plugin-mcp-manifest-unreadable');
+    }
+  }
+
   let declared: string[] = [];
   if (!existsSync(hooksPath)) {
     issues.push('codex-hook-manifest-missing');
@@ -479,7 +500,9 @@ async function inspectCodexHookTrust(): Promise<AgentPluginCheck> {
     kind: 'hook-trust',
     path: configPath,
     exists: true,
-    status: issues.length > 0 ? 'repairable' : 'ok',
+    // Codex records hook approval only after the user has reviewed it. Memorix
+    // must not treat an intentional, host-owned consent step as a broken setup.
+    status: issues.length > 0 ? 'skipped' : 'ok',
     issues,
     hookTrust: { trusted, expected: [...CODEX_HOOK_STATE_NAMES] },
   };
@@ -562,7 +585,7 @@ function getClaudeLocalConfigPath(): string {
   return `${homedir()}/.claude.json`;
 }
 
-function coerceClaudeLocalServer(name: string, value: unknown): MCPServerEntry | null {
+function coerceMcpServer(name: string, value: unknown): MCPServerEntry | null {
   const entry = asRecord(value);
   if (!entry) return null;
   const args = Array.isArray(entry.args) ? entry.args.map(String) : [];
@@ -626,7 +649,7 @@ async function inspectClaudeLocalMcp(projectRoot: string): Promise<AgentMcpCheck
   }
 
   const servers = asRecord(localProject.project.mcpServers);
-  const server = coerceClaudeLocalServer('memorix', servers?.memorix);
+  const server = coerceMcpServer('memorix', servers?.memorix);
   if (!server) {
     return {
       scope: 'local',
@@ -683,6 +706,59 @@ async function installClaudeLocalMcpConfig(projectRoot: string): Promise<void> {
   await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf-8');
 }
 
+async function inspectCodexPluginMcp(): Promise<AgentMcpCheck | null> {
+  const runtime = inspectCodexPluginRuntime();
+  if (!runtime.runtime?.installed || !runtime.runtime.enabled) return null;
+
+  const mcpPath = codexPluginMcpPath();
+  if (!existsSync(mcpPath)) {
+    return {
+      scope: 'global',
+      path: mcpPath,
+      exists: false,
+      status: 'repairable',
+      issues: ['codex-plugin-mcp-manifest-missing'],
+      managedByPlugin: true,
+    };
+  }
+
+  try {
+    const config = asRecord(JSON.parse(await readFile(mcpPath, 'utf-8')));
+    const server = coerceMcpServer('memorix', asRecord(config?.mcpServers)?.memorix);
+    if (!server) {
+      return {
+        scope: 'global',
+        path: mcpPath,
+        exists: true,
+        status: 'repairable',
+        issues: ['codex-plugin-mcp-manifest-invalid'],
+        managedByPlugin: true,
+      };
+    }
+    const issues: string[] = [];
+    if (looksLikeStaleMemorixCommand(server)) issues.push('stale-command-path');
+    if (!isRecommendedStdioServer(server)) issues.push('nonstandard-mcp-command');
+    return {
+      scope: 'global',
+      path: mcpPath,
+      exists: true,
+      status: issues.length > 0 ? 'repairable' : 'ok',
+      issues,
+      managedByPlugin: true,
+      server: sanitizeServer(server),
+    };
+  } catch {
+    return {
+      scope: 'global',
+      path: mcpPath,
+      exists: true,
+      status: 'repairable',
+      issues: ['codex-plugin-mcp-manifest-unreadable'],
+      managedByPlugin: true,
+    };
+  }
+}
+
 async function inspectMcp(agent: AgentName, projectRoot: string, scope: AgentIntegrationScope): Promise<AgentIntegrationEntry['mcp']> {
   if (!isMcpConfigAgent(agent)) {
     return { status: 'skipped', issues: ['mcp-managed-by-package'], checks: [] };
@@ -697,6 +773,14 @@ async function inspectMcp(agent: AgentName, projectRoot: string, scope: AgentInt
       continue;
     }
 
+    if (agent === 'codex' && targetScope === 'global') {
+      const pluginCheck = await inspectCodexPluginMcp();
+      if (pluginCheck) {
+        checks.push(pluginCheck);
+        continue;
+      }
+    }
+
     const configPath = adapter.getConfigPath(targetScope === 'project' ? projectRoot : undefined);
     if (targetScope === 'global' && configPath === adapter.getConfigPath(projectRoot)) continue;
 
@@ -872,11 +956,20 @@ export function formatAgentIntegrationReport(report: AgentIntegrationReport): st
     lines.push(`${entry.agent}: ${status}`);
     if (entry.mcp.issues.length > 0) lines.push(`  MCP: ${entry.mcp.issues.join(', ')}`);
     if (entry.guidance.issues.length > 0) lines.push(`  Guidance: ${entry.guidance.issues.join(', ')}`);
-    if (entry.plugin.issues.length > 0) lines.push(`  Plugin: ${entry.plugin.issues.join(', ')}`);
+    const hookTrustPending = entry.plugin.issues.includes('codex-hook-trust-pending');
+    const pluginIssues = entry.plugin.issues.filter((issue) => issue !== 'codex-hook-trust-pending');
+    if (pluginIssues.length > 0) lines.push(`  Plugin: ${pluginIssues.join(', ')}`);
+    if (hookTrustPending) {
+      lines.push('  Hooks: waiting for Codex approval on first use; MCP remains available.');
+    }
   }
 
   lines.push('');
-  lines.push(`Repair: ${report.repairCommand}`);
+  if (report.summary.missing > 0 || report.summary.repairable > 0) {
+    lines.push(`Repair: ${report.repairCommand}`);
+  } else {
+    lines.push('No file repair needed.');
+  }
   return lines.join('\n');
 }
 
@@ -899,6 +992,10 @@ export async function repairAgentIntegrations(options: {
     if (isMcpConfigAgent(entry.agent)) {
       for (const check of entry.mcp.checks) {
         if (check.status === 'ok' || check.status === 'skipped') continue;
+        if (check.managedByPlugin) {
+          skipped.push(`${entry.agent}:mcp:${check.scope}:plugin-managed`);
+          continue;
+        }
         if (check.status === 'missing' && !canInstallMissing) {
           skipped.push(`${entry.agent}:mcp:${check.scope}:missing`);
           continue;

package/src/cli/commands/serve-http.ts

@@ -839,10 +839,21 @@ export default defineCommand({
             };
           } catch { /* best effort */ }
 
-          let vectorStatus = { total: 0, missing: 0, missingIds: [] as number[], backfillRunning: false };
+          let vectorStatus = {
+            available: false,
+            total: 0,
+            missing: 0,
+            missingIds: [] as number[],
+            backfillRunning: false,
+          };
           try {
-            const { getVectorStatus } = await import('../../memory/observations.js');
-            vectorStatus = getVectorStatus(statsProjectId);
+            const { getSearchIndexStatus, getVectorStatus } = await import('../../memory/observations.js');
+            // The HTTP control plane has a different module graph from stdio MCP.
+            // Only report vector counts when this process actually owns a hydrated
+            // index; an empty singleton must not look like a healthy 0/0 state.
+            if (getSearchIndexStatus(statsProjectId).prepared) {
+              vectorStatus = { available: true, ...getVectorStatus(statsProjectId) };
+            }
           } catch { /* best effort */ }
 
           // Real search mode from the last actual search execution

package/src/cli/commands/setup.ts

@@ -484,6 +484,40 @@ function mergeTomlMcpConfig(existingContent: string | null, generatedContent: st
   return `${parts.join('\n\n')}\n`;
 }
 
+function isLegacyCodexMemorixNodeServer(server: MCPServerEntry): boolean {
+  if (server.name !== 'memorix' || server.command.trim().toLowerCase() !== 'node') return false;
+  const startsMemorixStdio = server.args.some((arg) => arg.trim().toLowerCase() === 'serve');
+  const sourceEntry = server.args.some((arg) => {
+    const normalized = arg.replace(/\\/g, '/').toLowerCase();
+    return /\/memorix\/dist\/cli\/index\.(?:[cm]?js)$/.test(normalized);
+  });
+  return startsMemorixStdio && sourceEntry;
+}
+
+/**
+ * Codex plugins now own Memorix stdio MCP registration. Remove only the old
+ * source-path form emitted by pre-plugin setup, never a user's custom server.
+ */
+export async function removeLegacyCodexMemorixMcpConfig(
+  configPath = path.join(homedir(), '.codex', 'config.toml'),
+): Promise<{ configPath: string; removed: boolean }> {
+  let existingContent: string;
+  try {
+    existingContent = await readFile(configPath, 'utf-8');
+  } catch {
+    return { configPath, removed: false };
+  }
+
+  const adapter = new CodexMCPAdapter();
+  const legacyServer = adapter.parse(existingContent).find(isLegacyCodexMemorixNodeServer);
+  if (!legacyServer) return { configPath, removed: false };
+
+  let nextContent = removeTomlSection(existingContent, 'mcp_servers.memorix.env');
+  nextContent = removeTomlSection(nextContent, 'mcp_servers.memorix');
+  await writeFile(configPath, nextContent ? `${nextContent}\n` : '', 'utf-8');
+  return { configPath, removed: true };
+}
+
 function mergeYamlMcpConfig(existingContent: string | null, generatedContent: string): string {
   let existing: Record<string, unknown> = {};
   try {
@@ -1091,6 +1125,16 @@ export async function installAgentSetup(agent: AgentName, plan: SetupPlan, globa
       const install = tryInstallCodexPlugin();
       if (install.ok) p.log.success(install.message);
       else p.log.warn(install.message);
+      if (install.ok) {
+        try {
+          const migration = await removeLegacyCodexMemorixMcpConfig();
+          if (migration.removed) {
+            p.log.info(`codex: removed legacy source-path MCP config from ${migration.configPath}`);
+          }
+        } catch {
+          p.log.warn('codex: plugin installed, but the legacy MCP config could not be checked');
+        }
+      }
     } else if (agent === 'claude' && result.marketplaceRoot) {
       const install = tryInstallClaudePlugin(result.marketplaceRoot);
       if (install.ok) p.log.success(install.message);

package/src/dashboard/server.ts

@@ -351,6 +351,17 @@ async function handleApi(
                     sourceCounts,
                     recentObservations: sorted,
                     embedding: embeddingStatus,
+                    // A standalone dashboard has no access to an active MCP
+                    // process's in-memory Orama index. Keep this explicit so the
+                    // UI never presents an empty local singleton as a healthy
+                    // all-vectors-indexed result.
+                    vectorStatus: {
+                        available: false,
+                        total: 0,
+                        missing: 0,
+                        missingIds: [],
+                        backfillRunning: false,
+                    },
                     storage: storageInfo,
                     maintenance,
                     ...(lifecycle ? { lifecycle } : {}),

package/src/memory/observations.ts

@@ -102,6 +102,10 @@ function normalizeEmbeddingFailure(error: unknown): { key: string; message: stri
   };
 }
 
+function vectorBackfillError(error: unknown): string {
+  return sanitizeCredentials(normalizeEmbeddingFailure(error).message).slice(0, 1_000);
+}
+
 function queueVectorBackfill(projectId: string): void {
   const dataDir = projectDir;
   if (!dataDir) return;
@@ -1202,6 +1206,7 @@ export async function backfillVectorEmbeddings(options: {
   attempted: number;
   succeeded: number;
   failed: number;
+  lastError?: string;
 }> {
   if (vectorBackfillRunning) {
     return { attempted: 0, succeeded: 0, failed: 0 };
@@ -1218,19 +1223,63 @@ export async function backfillVectorEmbeddings(options: {
   let succeeded = 0;
   let failed = 0;
   let lastFailure: string | undefined;
+  const recordFailure = (message: string): void => {
+    // A single batch may have several symptoms after one root cause. Preserve
+    // the first one so an informative provider/index error is not overwritten
+    // by later missing-result fallout.
+    if (!lastFailure) lastFailure = message;
+  };
+
+  const candidates: Array<{ id: number; observation: Observation; text: string }> = [];
+  for (const id of ids) {
+    const observation = observationById.get(id);
+    if (!observation) {
+      vectorMissingIds.delete(id);
+      continue;
+    }
+    candidates.push({
+      id,
+      observation,
+      text: [observation.title, observation.narrative, ...observation.facts].join(' '),
+    });
+  }
 
   try {
-    for (const id of ids) {
-      const obs = observationById.get(id);
-      if (!obs) {
-        vectorMissingIds.delete(id);
-        continue;
+    if (candidates.length === 0) {
+      return { attempted: ids.length, succeeded, failed };
+    }
+
+    let embeddings: number[][] | null = null;
+    try {
+      const provider = await getEmbeddingProvider();
+      if (!provider) {
+        if (isEmbeddingExplicitlyDisabled()) {
+          for (const candidate of candidates) vectorMissingIds.delete(candidate.id);
+        } else {
+          recordFailure('embedding provider unavailable');
+          failed += candidates.length;
+        }
+      } else {
+        // API providers batch and cache this efficiently; local providers can use
+        // their native batch path. Index writes stay sequential because Orama is
+        // process-local mutable state.
+        embeddings = await provider.embedBatch(candidates.map((candidate) => candidate.text));
       }
+    } catch (error) {
+      recordFailure(vectorBackfillError(error));
+      failed += candidates.length;
+    }
 
-      const text = [obs.title, obs.narrative, ...obs.facts].join(' ');
-      try {
-        const embedding = await generateEmbedding(text);
-        if (embedding) {
+    if (embeddings) {
+      for (let index = 0; index < candidates.length; index++) {
+        const { id, observation: obs } = candidates[index];
+        const embedding = embeddings[index];
+        if (!embedding || embedding.length === 0) {
+          recordFailure('embedding provider returned no vector');
+          failed++;
+          continue;
+        }
+        try {
           if (!isVectorCompatibleWithCurrentIndex(embedding)) {
             await upgradeVectorSchemaAfterFirstEmbedding(embedding);
           }
@@ -1239,7 +1288,7 @@ export async function backfillVectorEmbeddings(options: {
             console.error(
               `[memorix] Backfill embedding mismatch for obs-${id}: provider returned ${embedding.length}d, index expects ${vectorDimensions ?? 'unknown'}d (kept in queue)`,
             );
-            lastFailure = `dimension mismatch: provider returned ${embedding.length}d, index expects ${vectorDimensions ?? 'unknown'}d`;
+            recordFailure(`dimension mismatch: provider returned ${embedding.length}d, index expects ${vectorDimensions ?? 'unknown'}d`);
             failed++;
             continue;
           }
@@ -1277,17 +1326,10 @@ export async function backfillVectorEmbeddings(options: {
           await insertObservation(doc);
           vectorMissingIds.delete(id);
           succeeded++;
-        } else if (isEmbeddingExplicitlyDisabled()) {
-          // Embedding explicitly off — nothing to backfill from
-          vectorMissingIds.delete(id);
-        } else {
-          // Provider temporarily unavailable — keep in queue for next backfill cycle
-          lastFailure = 'embedding provider unavailable';
+        } catch (error) {
+          recordFailure(vectorBackfillError(error));
           failed++;
         }
-      } catch (err) {
-        lastFailure = err instanceof Error ? err.message : String(err);
-        failed++;
       }
     }
   } finally {
@@ -1301,5 +1343,10 @@ export async function backfillVectorEmbeddings(options: {
     };
   }
 
-  return { attempted: ids.length, succeeded, failed };
+  return {
+    attempted: ids.length,
+    succeeded,
+    failed,
+    ...(lastFailure ? { lastError: lastFailure } : {}),
+  };
 }

package/src/runtime/maintenance-jobs.ts

@@ -67,7 +67,18 @@ export interface MaintenanceJobSummary {
 
 export type MaintenanceJobRunResult =
   | { action: 'complete' }
-  | { action: 'reschedule'; delayMs: number; resetAttempts?: boolean; payload?: Record<string, unknown> };
+  | {
+    action: 'reschedule';
+    delayMs: number;
+    resetAttempts?: boolean;
+    payload?: Record<string, unknown>;
+    /** Keep recoverable work out of the immediate pending queue during a cooldown. */
+    status?: 'pending' | 'retry';
+    /** Persist a sanitized diagnostic without consuming the job's retry budget. */
+    lastError?: string;
+    /** Clear a stale transient diagnostic after the job makes progress. */
+    clearLastError?: boolean;
+  };
 
 export type MaintenanceJobHandler = (
   job: MaintenanceJob,
@@ -160,6 +171,12 @@ export class MaintenanceJobStore {
       `).get(input.projectId, input.kind, dedupeKey);
 
       if (existing) {
+        // A vector backfill in cooldown is a circuit-breaker state. A new MCP
+        // process must not pull it forward and recreate the original retry storm.
+        if (input.kind === 'vector-backfill' && existing.status === 'retry') {
+          this.commit();
+          return rowToJob(existing);
+        }
         const nextRunAfter = Math.min(Number(existing.run_after), runAfter);
         this.db.prepare(`
           UPDATE maintenance_jobs
@@ -171,6 +188,30 @@ export class MaintenanceJobStore {
         return rowToJob(updated);
       }
 
+      // Older releases exhausted vector jobs on transient provider/index errors.
+      // Reuse one failed record so the next healthy session recovers work instead
+      // of adding another permanent failure row for the same project.
+      if (input.kind === 'vector-backfill') {
+        const failed = this.db.prepare(`
+          SELECT * FROM maintenance_jobs
+          WHERE project_id = ? AND kind = ? AND dedupe_key = ? AND status = 'failed'
+          ORDER BY updated_at DESC
+          LIMIT 1
+        `).get(input.projectId, input.kind, dedupeKey);
+        if (failed) {
+          this.db.prepare(`
+            UPDATE maintenance_jobs
+            SET status = 'pending', attempts = 0, max_attempts = ?, run_after = ?,
+                payload_json = ?, lease_owner = NULL, lease_expires_at = NULL,
+                last_error = NULL, completed_at = NULL, updated_at = ?
+            WHERE id = ?
+          `).run(maxAttempts, runAfter, payloadJson, now, failed.id);
+          const revived = this.getRow(failed.id)!;
+          this.commit();
+          return rowToJob(revived);
+        }
+      }
+
       const id = randomUUID();
       this.db.prepare(`
         INSERT INTO maintenance_jobs (
@@ -361,21 +402,57 @@ export class MaintenanceJobStore {
   reschedule(
     id: string,
     workerId: string,
-    options: { delayMs: number; resetAttempts?: boolean; payload?: Record<string, unknown>; now?: number },
+    options: {
+      delayMs: number;
+      resetAttempts?: boolean;
+      payload?: Record<string, unknown>;
+      status?: 'pending' | 'retry';
+      lastError?: string;
+      clearLastError?: boolean;
+      now?: number;
+    },
   ): MaintenanceJob | undefined {
     const now = options.now ?? Date.now();
     const delayMs = Number.isFinite(options.delayMs) ? Math.max(0, Math.floor(options.delayMs)) : 0;
     const payloadJson = options.payload === undefined ? null : JSON.stringify(options.payload);
+    const status = options.status === 'retry' ? 'retry' : 'pending';
+    const hasLastError = options.lastError !== undefined;
+    const lastError = hasLastError ? errorText(options.lastError) : null;
     this.db.prepare(`
       UPDATE maintenance_jobs
-      SET status = 'pending', run_after = ?, attempts = CASE WHEN ? THEN 0 ELSE attempts END,
+      SET status = ?, run_after = ?, attempts = CASE WHEN ? THEN 0 ELSE attempts END,
           payload_json = COALESCE(?, payload_json),
+          last_error = CASE
+            WHEN ? THEN NULL
+            WHEN ? THEN ?
+            ELSE last_error
+          END,
           lease_owner = NULL, lease_expires_at = NULL, updated_at = ?
       WHERE id = ? AND status = 'running' AND lease_owner = ?
-    `).run(now + delayMs, options.resetAttempts ? 1 : 0, payloadJson, now, id, workerId);
+    `).run(
+      status,
+      now + delayMs,
+      options.resetAttempts ? 1 : 0,
+      payloadJson,
+      options.clearLastError ? 1 : 0,
+      hasLastError ? 1 : 0,
+      lastError,
+      now,
+      id,
+      workerId,
+    );
     return this.get(id);
   }
 
+  resolveFailedVectorBackfills(projectId: string, dedupeKey = 'vector-backfill', now = Date.now()): number {
+    const result = this.db.prepare(`
+      UPDATE maintenance_jobs
+      SET status = 'completed', completed_at = ?, updated_at = ?
+      WHERE project_id = ? AND kind = 'vector-backfill' AND dedupe_key = ? AND status = 'failed'
+    `).run(now, now, projectId, dedupeKey);
+    return Number(result.changes ?? 0);
+  }
+
   fail(id: string, workerId: string, error: unknown, now = Date.now()): MaintenanceJob | undefined {
     this.begin();
     try {
@@ -486,6 +563,9 @@ export class MaintenanceJobWorker {
             delayMs: result.delayMs,
             resetAttempts: result.resetAttempts,
             payload: result.payload,
+            status: result.status,
+            lastError: result.lastError,
+            clearLastError: result.clearLastError,
             now,
           });
           return { state: 'rescheduled', job: updated };