@vellumai/assistant 0.5.6 → 0.5.8

package/src/memory/migrations/registry.ts

@@ -1,3 +1,44 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { downJobDeferrals } from "./001-job-deferrals.js";
+import { downMemoryEntityRelationDedup } from "./004-entity-relation-dedup.js";
+import { downMemoryItemsFingerprintScopeUnique } from "./005-fingerprint-scope-unique.js";
+import { downMemoryItemsScopeSaltedFingerprints } from "./006-scope-salted-fingerprints.js";
+import { downAssistantIdToSelf } from "./007-assistant-id-to-self.js";
+import { downRemoveAssistantIdColumns } from "./008-remove-assistant-id-columns.js";
+import { downLlmUsageEventsDropAssistantId } from "./009-llm-usage-events-drop-assistant-id.js";
+import { downBackfillInboxThreadState } from "./014-backfill-inbox-thread-state.js";
+import { downDropActiveSearchIndex } from "./015-drop-active-search-index.js";
+import { downNotificationTablesSchema } from "./019-notification-tables-schema-migration.js";
+import { downRenameChannelToVellum } from "./020-rename-macos-ios-channel-to-vellum.js";
+import { downEmbeddingVectorBlob } from "./024-embedding-vector-blob.js";
+import { downEmbeddingsNullableVectorJson } from "./026a-embeddings-nullable-vector-json.js";
+import { downNormalizePhoneIdentities } from "./036-normalize-phone-identities.js";
+import { downBackfillGuardianPrincipalId } from "./126-backfill-guardian-principal-id.js";
+import { downGuardianPrincipalIdNotNull } from "./127-guardian-principal-id-not-null.js";
+import { downContactsNotesColumn } from "./134-contacts-notes-column.js";
+import { downBackfillContactInteractionStats } from "./135-backfill-contact-interaction-stats.js";
+import { downDropAssistantIdColumns } from "./136-drop-assistant-id-columns.js";
+import { downBackfillUsageCacheAccounting } from "./140-backfill-usage-cache-accounting.js";
+import { downRenameVerificationTable } from "./141-rename-verification-table.js";
+import { downRenameVerificationSessionIdColumn } from "./142-rename-verification-session-id-column.js";
+import { downRenameGuardianVerificationValues } from "./143-rename-guardian-verification-values.js";
+import { downRenameVoiceToPhone } from "./144-rename-voice-to-phone.js";
+import { migrateDropAccountsTableDown } from "./145-drop-accounts-table.js";
+import { migrateRemindersToSchedulesDown } from "./147-migrate-reminders-to-schedules.js";
+import { migrateDropRemindersTableDown } from "./148-drop-reminders-table.js";
+import { migrateOAuthAppsClientSecretPathDown } from "./150-oauth-apps-client-secret-path.js";
+import {
+  migrateGuardianTimestampsEpochMsDown,
+  migrateGuardianTimestampsRebuildDown,
+} from "./162-guardian-timestamps-epoch-ms.js";
+import { migrateRenameGmailProviderKeyToGoogleDown } from "./169-rename-gmail-provider-key-to-google.js";
+import { migrateRenameThreadStartersTableDown } from "./174-rename-thread-starters-table.js";
+import { migrateDropCapabilityCardStateDown } from "./176-drop-capability-card-state.js";
+import { migrateBackfillInlineAttachmentsToDiskDown } from "./180-backfill-inline-attachments-to-disk.js";
+import { migrateRenameThreadStartersCheckpointsDown } from "./181-rename-thread-starters-checkpoints.js";
+import { migrateBackfillAudioAttachmentMimeTypesDown } from "./191-backfill-audio-attachment-mime-types.js";
+import { migrateAddSourceTypeColumnsDown } from "./193-add-source-type-columns.js";
+
 export interface MigrationRegistryEntry {
   /** The checkpoint key written to memory_checkpoints on completion. */
   key: string;
@@ -7,6 +48,8 @@ export interface MigrationRegistryEntry {
   dependsOn?: string[];
   /** Human-readable description for diagnostics and future authorship guidance. */
   description: string;
+  /** Reverse the migration. Must be idempotent — safe to re-run. */
+  down: (database: DrizzleDb) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -26,18 +69,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     version: 1,
     description:
       "Reconcile legacy deferral history from attempts column into deferrals column",
+    down: downJobDeferrals,
   },
   {
     key: "migration_memory_entity_relations_dedup_v1",
     version: 2,
     description:
       "Deduplicate entity relation edges before enforcing the (source, target, relation) unique index",
+    down: downMemoryEntityRelationDedup,
   },
   {
     key: "migration_memory_items_fingerprint_scope_unique_v1",
     version: 3,
     description:
       "Replace column-level UNIQUE on fingerprint with compound (fingerprint, scope_id) unique index",
+    down: downMemoryItemsFingerprintScopeUnique,
   },
   {
     key: "migration_memory_items_scope_salted_fingerprints_v1",
@@ -45,12 +91,14 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_memory_items_fingerprint_scope_unique_v1"],
     description:
       "Recompute memory item fingerprints to include scope_id prefix after schema change",
+    down: downMemoryItemsScopeSaltedFingerprints,
   },
   {
     key: "migration_normalize_assistant_id_to_self_v1",
     version: 5,
     description:
       'Normalize all assistant_id values in scoped tables to the implicit "self" single-tenant identity',
+    down: downAssistantIdToSelf,
   },
   {
     key: "migration_remove_assistant_id_columns_v1",
@@ -58,6 +106,7 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_normalize_assistant_id_to_self_v1"],
     description:
       "Rebuild four tables to drop the assistant_id column after normalization",
+    down: downRemoveAssistantIdColumns,
   },
   {
     key: "migration_remove_assistant_id_lue_v1",
@@ -65,36 +114,42 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_normalize_assistant_id_to_self_v1"],
     description:
       "Remove assistant_id column from llm_usage_events (separate checkpoint from the four-table migration)",
+    down: downLlmUsageEventsDropAssistantId,
   },
   {
     key: "backfill_inbox_thread_state_from_bindings",
     version: 8,
     description:
       "Seed assistant_inbox_thread_state from external_conversation_bindings",
+    down: downBackfillInboxThreadState,
   },
   {
     key: "drop_active_search_index_v1",
     version: 9,
     description:
       "Drop old idx_memory_items_active_search so it can be recreated with updated covering columns",
+    down: downDropActiveSearchIndex,
   },
   {
     key: "migration_notification_tables_schema_v1",
     version: 10,
     description:
       "Drop legacy enum-based notification tables so they can be recreated with the new signal-contract schema",
+    down: downNotificationTablesSchema,
   },
   {
     key: "migration_rename_macos_ios_channel_to_vellum_v1",
     version: 11,
     description:
       "Rename macos and ios channel identifiers to vellum across all tables",
+    down: downRenameChannelToVellum,
   },
   {
     key: "migration_embedding_vector_blob_v1",
     version: 12,
     description:
       "Add vector_blob BLOB column to memory_embeddings and backfill from vector_json for compact binary storage",
+    down: downEmbeddingVectorBlob,
   },
   {
     key: "migration_embeddings_nullable_vector_json_v1",
@@ -102,18 +157,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_embedding_vector_blob_v1"],
     description:
       "Rebuild memory_embeddings to make vector_json nullable (pre-100 DBs had NOT NULL)",
+    down: downEmbeddingsNullableVectorJson,
   },
   {
     key: "migration_normalize_phone_identities_v1",
     version: 14,
     description:
       "Normalize phone-like identity fields to E.164 format across guardian bindings, verification challenges, canonical requests, ingress members, and rate limits",
+    down: downNormalizePhoneIdentities,
   },
   {
     key: "migration_backfill_guardian_principal_id_v3",
     version: 15,
     description:
       "Backfill guardianPrincipalId for existing channel_guardian_bindings and canonical_guardian_requests rows, expire unresolvable pending requests",
+    down: downBackfillGuardianPrincipalId,
   },
   {
     key: "migration_guardian_principal_id_not_null_v1",
@@ -121,18 +179,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_backfill_guardian_principal_id_v3"],
     description:
       "Enforce NOT NULL on channel_guardian_bindings.guardian_principal_id after backfill",
+    down: downGuardianPrincipalIdNotNull,
   },
   {
     key: "migration_contacts_notes_column_v1",
     version: 17,
     description:
       "Consolidate relationship/importance/response_expectation/preferred_tone into a single notes TEXT column, then drop the legacy columns",
+    down: downContactsNotesColumn,
   },
   {
     key: "backfill_contact_interaction_stats",
     version: 18,
     description:
       "Backfill contacts.last_interaction from the max lastSeenAt across each contact's channels",
+    down: downBackfillContactInteractionStats,
   },
   {
     key: "migration_drop_assistant_id_columns_v1",
@@ -140,48 +201,56 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_normalize_assistant_id_to_self_v1"],
     description:
       "Drop assistant_id columns from all 16 daemon tables after normalization to single-tenant identity",
+    down: downDropAssistantIdColumns,
   },
   {
     key: "migration_backfill_usage_cache_accounting_v1",
     version: 20,
     description:
       "Backfill historical Anthropic llm_usage_events rows from llm_request_logs with cache-aware pricing",
+    down: downBackfillUsageCacheAccounting,
   },
   {
     key: "migration_rename_verification_table_v1",
     version: 21,
     description:
       "Rename channel_guardian_verification_challenges table to channel_verification_sessions and update indexes",
+    down: downRenameVerificationTable,
   },
   {
     key: "migration_rename_verification_session_id_column_v1",
     version: 22,
     description:
       "Rename guardian_verification_session_id column in call_sessions to verification_session_id",
+    down: downRenameVerificationSessionIdColumn,
   },
   {
     key: "migration_rename_guardian_verification_values_v1",
     version: 23,
     description:
       "Rename persisted guardian_verification call_mode and guardian_voice_verification_* event_type values to drop the guardian_ prefix",
+    down: downRenameGuardianVerificationValues,
   },
   {
     key: "migration_rename_voice_to_phone_v1",
     version: 24,
     description:
       'Rename stored "voice" channel values to "phone" across all tables with channel text columns',
+    down: downRenameVoiceToPhone,
   },
   {
     key: "migration_drop_accounts_table_v1",
     version: 25,
     description:
       "Drop the unused legacy accounts table and its leftover indexes after account_manage removal",
+    down: migrateDropAccountsTableDown,
   },
   {
     key: "migration_reminders_to_schedules_v1",
     version: 26,
     description:
       "Copy all existing reminders into cron_jobs as one-shot schedules with correct status and field mapping",
+    down: migrateRemindersToSchedulesDown,
   },
   {
     key: "migration_drop_reminders_table_v1",
@@ -189,18 +258,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_reminders_to_schedules_v1"],
     description:
       "Drop the legacy reminders table and its index after data migration to cron_jobs",
+    down: migrateDropRemindersTableDown,
   },
   {
     key: "migration_oauth_apps_client_secret_path_v1",
     version: 28,
     description:
       "Add client_secret_credential_path column to oauth_apps and backfill existing rows with convention-based paths",
+    down: migrateOAuthAppsClientSecretPathDown,
   },
   {
     key: "migration_guardian_timestamps_epoch_ms_v1",
     version: 29,
     description:
       "Convert guardian table timestamps from ISO 8601 text to epoch ms integers for consistency with all other tables",
+    down: migrateGuardianTimestampsEpochMsDown,
   },
   {
     key: "migration_guardian_timestamps_rebuild_v1",
@@ -208,18 +280,21 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_guardian_timestamps_epoch_ms_v1"],
     description:
       "Rebuild guardian tables so timestamp columns have INTEGER affinity instead of TEXT",
+    down: migrateGuardianTimestampsRebuildDown,
   },
   {
     key: "migration_rename_gmail_provider_key_to_google_v1",
     version: 31,
     description:
       "Rename integration:gmail provider key to integration:google across oauth_providers, oauth_apps, and oauth_connections",
+    down: migrateRenameGmailProviderKeyToGoogleDown,
   },
   {
     key: "migration_rename_thread_starters_table_v1",
     version: 32,
     description:
       "Rename thread_starters table to conversation_starters and recreate indexes with new names",
+    down: migrateRenameThreadStartersTableDown,
   },
   {
     key: "migration_drop_capability_card_state_v1",
@@ -227,12 +302,14 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_rename_thread_starters_table_v1"],
     description:
       "Remove deleted capability-card rows, jobs, checkpoints, and category state",
+    down: migrateDropCapabilityCardStateDown,
   },
   {
     key: "migration_backfill_inline_attachments_v1",
     version: 34,
     description:
       "Backfill existing inline base64 attachments to on-disk storage and clear dataBase64",
+    down: migrateBackfillInlineAttachmentsToDiskDown,
   },
   {
     key: "migration_rename_thread_starters_checkpoints_v1",
@@ -240,12 +317,33 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     dependsOn: ["migration_rename_thread_starters_table_v1"],
     description:
       "Rename checkpoint keys from thread_starters: to conversation_starters: prefix so renamed code paths find existing generation state",
+    down: migrateRenameThreadStartersCheckpointsDown,
+  },
+  {
+    key: "migration_backfill_audio_attachment_mime_types_v1",
+    version: 36,
+    description:
+      "Backfill correct MIME types for audio attachments stored as application/octet-stream due to missing extension map entries",
+    down: migrateBackfillAudioAttachmentMimeTypesDown,
+  },
+  {
+    key: "migration_add_source_type_columns_v1",
+    version: 37,
+    description:
+      "Add source_type and source_message_role columns to memory_items with backfill from verification_state and source messages",
+    down: migrateAddSourceTypeColumnsDown,
   },
 ];
 
+export function getMaxMigrationVersion(): number {
+  return Math.max(...MIGRATION_REGISTRY.map((e) => e.version));
+}
+
 export interface MigrationValidationResult {
   /** Keys of migrations whose checkpoint has value 'started' — started but never completed. */
   crashed: string[];
   /** Pairs where a completed migration's declared prerequisite is missing from checkpoints. */
   dependencyViolations: Array<{ migration: string; missingDependency: string }>;
+  /** Checkpoint keys present in the database but absent from the migration registry — likely from a newer version. */
+  unknownCheckpoints: string[];
 }

package/src/memory/migrations/validate-migration-state.ts

@@ -33,7 +33,9 @@ export function recoverCrashedMigrations(database: DrizzleDb): string[] {
     return [];
   }
 
-  const crashed = rows.filter((r) => r.value === "started").map((r) => r.key);
+  const crashed = rows
+    .filter((r) => r.value === "started" || r.value === "rolling_back")
+    .map((r) => r.key);
   if (crashed.length === 0) return [];
 
   log.error(
@@ -83,7 +85,12 @@ export function withCrashRecovery(
   const existing = raw
     .query(`SELECT value FROM memory_checkpoints WHERE key = ?`)
     .get(checkpointKey) as { value: string } | null;
-  if (existing && existing.value !== "started") return;
+  if (
+    existing &&
+    existing.value !== "started" &&
+    existing.value !== "rolling_back"
+  )
+    return;
 
   raw
     .query(
@@ -126,12 +133,14 @@ export function validateMigrationState(
       .all() as Array<{ key: string; value: string }>;
   } catch {
     // memory_checkpoints may not exist on a very old database; skip.
-    return { crashed: [], dependencyViolations: [] };
+    return { crashed: [], dependencyViolations: [], unknownCheckpoints: [] };
   }
 
-  // Any remaining 'started' checkpoints after recovery + migration execution
-  // indicate a migration that was retried but failed again.
-  const crashed = rows.filter((r) => r.value === "started").map((r) => r.key);
+  // Any remaining 'started' or 'rolling_back' checkpoints after recovery +
+  // migration execution indicate a migration that was retried but failed again.
+  const crashed = rows
+    .filter((r) => r.value === "started" || r.value === "rolling_back")
+    .map((r) => r.key);
   if (crashed.length > 0) {
     log.error(
       { crashed },
@@ -149,11 +158,14 @@ export function validateMigrationState(
     );
   }
 
-  // Only rows whose value is NOT 'started' represent truly completed migrations.
-  // In-progress/crashed checkpoints (value = 'started') must not count as applied
-  // dependencies — the migration never finished, so its postconditions are unmet.
+  // Only rows whose value is NOT 'started' or 'rolling_back' represent truly
+  // completed migrations. In-progress/crashed checkpoints must not count as
+  // applied dependencies — the migration never finished, so its postconditions
+  // are unmet.
   const completed = new Set(
-    rows.filter((r) => r.value !== "started").map((r) => r.key),
+    rows
+      .filter((r) => r.value !== "started" && r.value !== "rolling_back")
+      .map((r) => r.key),
   );
 
   const dependencyViolations: Array<{
@@ -191,5 +203,119 @@ export function validateMigrationState(
     );
   }
 
-  return { crashed, dependencyViolations };
+  // Detect checkpoints that exist in the database but have no corresponding
+  // registry entry — these are from a newer version of the daemon.
+  //
+  // The memory_checkpoints table is a general-purpose key-value store also
+  // used by non-migration subsystems (e.g., "identity:intro:text",
+  // "conversation_starters:item_count_at_last_gen"). Filter to only keys
+  // that follow migration naming conventions before comparing against the
+  // registry to avoid false-positive warnings.
+  const registryKeys = new Set(MIGRATION_REGISTRY.map((e) => e.key));
+  const isMigrationKey = (k: string): boolean =>
+    k.startsWith("migration_") ||
+    k.startsWith("backfill_") ||
+    k.startsWith("drop_");
+  const unknownCheckpoints = [...completed].filter(
+    (k) => isMigrationKey(k) && !registryKeys.has(k),
+  );
+
+  if (unknownCheckpoints.length > 0) {
+    log.warn(
+      { unknownCheckpoints },
+      `Database contains ${unknownCheckpoints.length} migration checkpoint(s) from a newer version. Data may be incompatible.`,
+    );
+  }
+
+  return { crashed, dependencyViolations, unknownCheckpoints };
+}
+
+/**
+ * Roll back all completed memory (database) migrations with version > targetVersion.
+ *
+ * Iterates eligible migrations in reverse version order. For each:
+ * 1. Marks the checkpoint as `"rolling_back"` for crash recovery.
+ * 2. Calls `entry.down(database)` — each down() manages its own transactions.
+ *    (`down` is required on `MigrationRegistryEntry` at the type level.)
+ * 3. Deletes the checkpoint from `memory_checkpoints`.
+ *
+ * **Usage**: Pass the target version number you want to roll back *to*. All
+ * migrations with a higher version number that have been applied will be
+ * reversed. For example, `rollbackMemoryMigration(db, 5)` rolls back all
+ * applied migrations with version > 5.
+ *
+ * **Checkpoint state**: Each rolled-back migration's checkpoint is deleted
+ * from `memory_checkpoints`. If the process crashes mid-rollback, the
+ * `"rolling_back"` marker is detected and cleared by
+ * `recoverCrashedMigrations` on the next startup.
+ *
+ * **Warning — data loss**: Some down() migrations may not fully restore the
+ * original state (e.g., DROP TABLE migrations recreate the table but cannot
+ * recover the original data). Review each migration's down() implementation
+ * before calling this function programmatically.
+ *
+ * **Important**: Stop the assistant before running rollbacks. Rolling back
+ * migrations while the assistant is running may cause schema mismatches,
+ * query failures, or data corruption.
+ *
+ * @param database  The Drizzle database instance.
+ * @param targetVersion  Roll back to this version (exclusive — all migrations
+ *   with version > targetVersion are reversed).
+ * @returns The list of rolled-back migration keys.
+ */
+export function rollbackMemoryMigration(
+  database: DrizzleDb,
+  targetVersion: number,
+): string[] {
+  const raw = getSqliteFrom(database);
+
+  // Read completed checkpoints to determine which migrations have been applied.
+  let rows: Array<{ key: string; value: string }>;
+  try {
+    rows = raw
+      .query(`SELECT key, value FROM memory_checkpoints`)
+      .all() as Array<{ key: string; value: string }>;
+  } catch {
+    return [];
+  }
+
+  const completedKeys = new Set(
+    rows
+      .filter((r) => r.value !== "started" && r.value !== "rolling_back")
+      .map((r) => r.key),
+  );
+
+  // Find registry entries with version > targetVersion that have completed checkpoints.
+  const toRollback = MIGRATION_REGISTRY.filter(
+    (entry) => entry.version > targetVersion && completedKeys.has(entry.key),
+  ).sort((a, b) => b.version - a.version); // reverse version order
+
+  const rolledBack: string[] = [];
+
+  for (const entry of toRollback) {
+    // Mark as rolling_back for crash recovery — if the process crashes here,
+    // recoverCrashedMigrations will clear this checkpoint on next startup.
+    raw
+      .query(
+        `UPDATE memory_checkpoints SET value = 'rolling_back', updated_at = ? WHERE key = ?`,
+      )
+      .run(Date.now(), entry.key);
+
+    // Execute the down migration — let it manage its own transaction lifecycle.
+    // Many down() functions call BEGIN/COMMIT internally or use PRAGMA statements
+    // that are no-ops inside a transaction.
+    entry.down(database);
+
+    // Delete the checkpoint after down() succeeds — outside any transaction
+    // so it's not affected by down()'s internal transaction management.
+    raw.query(`DELETE FROM memory_checkpoints WHERE key = ?`).run(entry.key);
+
+    log.info(
+      { key: entry.key, version: entry.version },
+      `Rolled back migration "${entry.key}" (version ${entry.version})`,
+    );
+    rolledBack.push(entry.key);
+  }
+
+  return rolledBack;
 }

package/src/memory/qdrant-circuit-breaker.ts

@@ -101,6 +101,15 @@ export function isQdrantBreakerOpen(): boolean {
   return breakerState !== "closed";
 }
 
+/**
+ * Returns true when the breaker is open and the cooldown has elapsed,
+ * meaning the next call to `withQdrantBreaker` will transition to half-open.
+ * Use this to allow a single probe job through when embed jobs are otherwise skipped.
+ */
+export function shouldAllowQdrantProbe(): boolean {
+  return breakerState === "open" && Date.now() - openedAt >= COOLDOWN_MS;
+}
+
 /** @internal Test-only: reset circuit breaker state */
 export function _resetQdrantBreaker(): void {
   breakerState = "closed";

package/src/memory/qdrant-manager.ts

@@ -4,6 +4,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  symlinkSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -12,7 +13,7 @@ import { dirname, join } from "node:path";
 
 import type { Subprocess } from "bun";
 
-import { getQdrantUrlEnv } from "../config/env.js";
+import { getQdrantReadyzTimeoutMs, getQdrantUrlEnv } from "../config/env.js";
 import { getLogger } from "../util/logger.js";
 import { getDataDir } from "../util/platform.js";
 
@@ -47,6 +48,8 @@ export interface QdrantManagerConfig {
  */
 export class QdrantManager {
   private process: Subprocess | null = null;
+  private stderrBuffer = "";
+  private stderrDrained: Promise<void> = Promise.resolve();
   private readonly url: string;
   private readonly host: string;
   private readonly port: number;
@@ -67,7 +70,8 @@ export class QdrantManager {
 
     this.readyzPollIntervalMs =
       config.readyzPollIntervalMs ?? READYZ_POLL_INTERVAL_MS;
-    this.readyzTimeoutMs = config.readyzTimeoutMs ?? READYZ_TIMEOUT_MS;
+    this.readyzTimeoutMs =
+      config.readyzTimeoutMs ?? getQdrantReadyzTimeoutMs() ?? READYZ_TIMEOUT_MS;
     this.shutdownGraceMs = config.shutdownGraceMs ?? SHUTDOWN_GRACE_MS;
 
     // External mode only if QDRANT_URL is explicitly set
@@ -92,13 +96,15 @@ export class QdrantManager {
       await this.installBinary(binaryPath);
     }
 
+    const spawnPath = this.ensureVellumSymlink(binaryPath);
+
     log.info(
-      { binaryPath, storagePath: this.storagePath, port: this.port },
+      { binaryPath: spawnPath, storagePath: this.storagePath, port: this.port },
       "Starting Qdrant",
     );
 
-    this.process = Bun.spawn({
-      cmd: [binaryPath],
+    const proc = Bun.spawn({
+      cmd: [spawnPath],
       env: {
         ...process.env,
         QDRANT__SERVICE__HOST: this.host,
@@ -109,8 +115,10 @@ export class QdrantManager {
         QDRANT__LOG_LEVEL: "WARN",
       },
       stdout: "ignore",
-      stderr: "ignore",
+      stderr: "pipe",
     });
+    this.process = proc;
+    this.drainStderrFrom(proc.stderr);
 
     if (this.process.pid) {
       this.writePid(this.process.pid);
@@ -150,6 +158,7 @@ export class QdrantManager {
     }
 
     this.process = null;
+    this.stderrBuffer = "";
     this.cleanupPid();
     log.info("Qdrant stopped");
   }
@@ -259,6 +268,15 @@ export class QdrantManager {
   private async waitForReady(): Promise<void> {
     const start = Date.now();
     while (Date.now() - start < this.readyzTimeoutMs) {
+      // Fail fast if the managed process exited before becoming ready
+      if (this.process != null && this.process.exitCode != null) {
+        await this.stderrDrained;
+        const stderr = this.stderrBuffer.trim();
+        throw new Error(
+          `Qdrant process exited with code ${this.process.exitCode} before becoming ready` +
+            (stderr ? `\nstderr:\n${stderr}` : ""),
+        );
+      }
       try {
         const res = await fetch(`${this.url}/readyz`);
         if (res.ok) return;
@@ -267,11 +285,32 @@ export class QdrantManager {
       }
       await Bun.sleep(this.readyzPollIntervalMs);
     }
+    const stderr = this.stderrBuffer.trim();
     throw new Error(
-      `Qdrant did not become ready within ${this.readyzTimeoutMs}ms at ${this.url}`,
+      `Qdrant did not become ready within ${this.readyzTimeoutMs}ms at ${this.url}` +
+        (stderr ? `\nstderr:\n${stderr}` : ""),
     );
   }
 
+  private drainStderrFrom(stream: ReadableStream<Uint8Array>): void {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    this.stderrDrained = (async () => {
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          this.stderrBuffer += decoder.decode(value, { stream: true });
+          if (this.stderrBuffer.length > 4096) {
+            this.stderrBuffer = this.stderrBuffer.slice(-4096);
+          }
+        }
+      } catch {
+        // Stream closed or error — expected during shutdown
+      }
+    })();
+  }
+
   private getBinaryPath(): string {
     return join(getDataDir(), "qdrant", "bin", "qdrant");
   }
@@ -314,4 +353,22 @@ export class QdrantManager {
       }
     }
   }
+
+  /**
+   * Ensures a `vellum-qdrant` symlink exists next to the real binary so that
+   * `lsof` reports "vellum-qdrant" in the COMMAND column, making the process
+   * discoverable by tools that scan for "vellum" in process names.
+   */
+  private ensureVellumSymlink(binaryPath: string): string {
+    const symlinkPath = join(dirname(binaryPath), "vellum-qdrant");
+    if (!existsSync(symlinkPath)) {
+      try {
+        symlinkSync(binaryPath, symlinkPath);
+      } catch {
+        // Fall back to the real binary if symlink creation fails
+        return binaryPath;
+      }
+    }
+    return symlinkPath;
+  }
 }