@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/permissions/checker.test.ts

@@ -15,13 +15,16 @@ mock.module("../config/assistant-feature-flags.js", () => ({
 }));
 
 // `buildPolicyContext` (used by the integration tests below) precomputes the
-// proc-to-skills gate via `isV3TierActive`. Drive it through this slot so a
-// test can put the production threading path in the active / inactive state.
+// retrospective skill-improvement gate. Keep the v3 tier active while the
+// dedicated gate changes so the production threading test covers the new
+// opt-out rather than the old v3 condition.
 let mockV3TierActive = true;
+let mockSkillImprovementActive = true;
 mock.module("../config/memory-v3-gate.js", () => ({
   isMemoryEnabled: (config?: { memory?: { enabled?: boolean } }) =>
     config?.memory?.enabled !== false,
   isV3TierActive: () => mockV3TierActive,
+  isSkillImprovementActive: () => mockSkillImprovementActive,
   isMemoryV3Live: () => mockV3TierActive,
   usesConceptPageMemory: (memory?: {
     enabled?: boolean;
@@ -219,6 +222,7 @@ describe("Permission Checker (gateway IPC)", () => {
     mockCachedThreshold = "low";
     mockRefreshedThreshold = null;
     mockV3TierActive = true;
+    mockSkillImprovementActive = true;
     thresholdCallLog.length = 0;
     mockSkillCatalog = [];
     mockResolvedSkill = null;
@@ -1173,10 +1177,11 @@ describe("Permission Checker (gateway IPC)", () => {
     });
 
     test("grant does NOT fire when proc-to-skills is inactive, even for the retrospective turn", async () => {
-      // Same retrospective ToolContext, but the feature is inactive (flag off
-      // or v3 not live). buildPolicyContext stamps `procToSkillsActive: false`,
-      // so the grant is dead and the high-risk scaffold prompts.
-      mockV3TierActive = false;
+      // The retrospective keeps its live v3 tier, but this independent flag is
+      // off. buildPolicyContext stamps `procToSkillsActive: false`, so the
+      // grant is dead and the high-risk scaffold prompts.
+      mockV3TierActive = true;
+      mockSkillImprovementActive = false;
       mockIpcClassifyRiskResult = {
         risk: "high",
         reason: "Skill scaffold",

package/src/persistence/compaction-log-store-clickhouse.ts

@@ -26,6 +26,7 @@
  */
 import type { AgentEvent } from "../agent/loop.js";
 import { getConfig } from "../config/loader.js";
+import { resolvePlatformAssistantIdOrNull } from "../config/platform-identity.js";
 import type { CompactionLogsClickHouseConfig } from "../config/schemas/compaction-logs.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
@@ -136,7 +137,7 @@ export interface ClickHouseCompactionLogStoreDeps {
   resolveUrl?: () => Promise<string | null>;
   /** Override the credential read for `clickhouse:password`. */
   resolvePassword?: () => Promise<string | null>;
-  /** Override the credential read for `vellum:platform_assistant_id`. */
+  /** Override the in-memory platform assistant id. */
   resolveAssistantId?: () => Promise<string | null>;
   /** Override fetch for testing. */
   fetchImpl?: CompactionLogFetch;
@@ -163,8 +164,7 @@ export class ClickHouseCompactionLogStore {
       deps.resolvePassword ??
       (() => readCredentialOrNull("clickhouse", "password"));
     this.resolveAssistantId =
-      deps.resolveAssistantId ??
-      (() => readCredentialOrNull("vellum", "platform_assistant_id"));
+      deps.resolveAssistantId ?? resolvePlatformAssistantIdOrNull;
     this.fetchImpl = deps.fetchImpl ?? globalThis.fetch.bind(globalThis);
   }
 

package/src/persistence/conversation-crud.ts

@@ -35,7 +35,10 @@ import { findConversation } from "../daemon/conversation-registry.js";
 import { conversationMetadataSyncTag } from "../daemon/message-types/sync.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
 import { clearAllConversationIds } from "../home/feed-writer.js";
-import type { ConversationDeletedInputContext } from "../hooks/types.js";
+import type {
+  ConversationDeletedInputContext,
+  MessageDeletedInputContext,
+} from "../hooks/types.js";
 import { readProviderMetadata } from "../messaging/read-provider-metadata.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import { forkConversationMemory } from "../plugins/defaults/memory/fork-conversation-memory.js";
@@ -81,7 +84,6 @@ import { ensureDisplayOrderMigration } from "./conversation-display-order-migrat
 import { ensureGroupMigration } from "./conversation-group-migration.js";
 import {
   isReferentialFork,
-  type LineageBound,
   type LineageConversationRow,
   lineageMessageFilter,
   lineageMessagesAfterFilter,
@@ -121,6 +123,11 @@ import {
 } from "./job-handlers/message-lexical.js";
 import { buildLifecycleTelemetryEvent } from "./lifecycle-events-store.js";
 import { resolveMessageContentBlocks } from "./message-content-file.js";
+import {
+  loadMessageBound,
+  type MessagesAfterRef,
+  resolveMessagesAfterBound,
+} from "./message-cursor.js";
 import { mergeMessageMetadata } from "./message-metadata.js";
 import {
   rawAll,
@@ -2641,16 +2648,6 @@ function loadLineageRow(id: string): LineageConversationRow | null {
   return row ?? null;
 }
 
-/** The `(createdAt, id)` bound of a single message, or null when it is gone. */
-function loadMessageBound(messageId: string): LineageBound | null {
-  const row = getDb()
-    .select({ createdAt: messages.createdAt, id: messages.id })
-    .from(messages)
-    .where(eq(messages.id, messageId))
-    .get();
-  return row ?? null;
-}
-
 /**
  * The segments making up a conversation's logical message set. Non-forks and
  * copied forks resolve to a single unbounded segment after one row lookup, so
@@ -2972,81 +2969,67 @@ export function selectNewestSightFrameCapture(
 }
 
 /**
- * Count messages in a conversation that were created strictly after the
- * `afterMessageId` reference message. If `afterMessageId` is `null` or empty,
- * counts all messages in the conversation. If the referenced message no
- * longer exists (e.g. deleted by a separate flow), returns 0 — callers
- * decide how to react to a vanished reference, and the conservative answer
- * here is "no new work."
+ * Count messages in a conversation created strictly after the `after`
+ * reference. `null`, `""`, or a cursor with an empty id counts every message.
+ * The reference resolves through `resolveMessagesAfterBound`: a live row's
+ * `(createdAt, id)` is authoritative, a `MessageCursor` whose row has been
+ * deleted still bounds the count from the `createdAt` it carries, and a bare
+ * id whose row is gone counts 0: a caller holding only an id has no
+ * defensible starting point, and the conservative answer is "no new work."
  *
  * Used by the memory-retrospective trigger check to decide whether to fire
  * the message-count trigger without loading message bodies.
  */
 export function countMessagesAfter(
   conversationId: string,
-  afterMessageId: string | null,
+  after: MessagesAfterRef,
 ): number {
   const db = getDb();
   const segments = resolveLineage(conversationId);
-  if (afterMessageId === null || afterMessageId === "") {
-    const row = db
-      .select({ c: count() })
-      .from(messages)
-      .where(lineageMessageFilter(segments))
-      .get();
-    return row?.c ?? 0;
-  }
-  const ref = loadMessageBound(afterMessageId);
-  if (!ref) {
+  const start = resolveMessagesAfterBound(after);
+  if (start.kind === "vanished") {
     return 0;
   }
-  // Tie-breaker on `messages.id` so rows that share a millisecond timestamp
-  // with the reference are not permanently skipped. Mirrors the
-  // `(createdAt, id)` cursor pattern used by the backfill job-handler and
-  // turn-events-store.
   const row = db
     .select({ c: count() })
     .from(messages)
-    .where(lineageMessagesAfterFilter(segments, ref))
+    .where(
+      start.kind === "all"
+        ? lineageMessageFilter(segments)
+        : lineageMessagesAfterFilter(segments, start.bound),
+    )
     .get();
   return row?.c ?? 0;
 }
 
 /**
- * Return messages in a conversation created strictly after the
- * `afterMessageId` reference. If the reference is `null`/empty, returns all
- * messages. If the reference doesn't exist, returns an empty array (mirrors
- * `countMessagesAfter`'s conservative semantics). Used by the
- * memory-retrospective job handler to load the message slice it processes.
+ * Return messages in a conversation created strictly after the `after`
+ * reference, in `(createdAt, id)` order. Resolves the reference exactly as
+ * `countMessagesAfter` does, returning an empty array where that returns 0.
+ * Used by the memory-retrospective job handler to load the message slice it
+ * processes.
  */
 export function getMessagesAfter(
   conversationId: string,
-  afterMessageId: string | null,
+  after: MessagesAfterRef,
 ): MessageRow[] {
   const db = getDb();
   const segments = resolveLineage(conversationId);
-  if (afterMessageId === null || afterMessageId === "") {
-    // Secondary `asc(messages.id)` matches the non-null path's cursor
-    // ordering, so callers tracking `cutoffMessageId` across runs see a
-    // consistent ordering when multiple rows share a millisecond timestamp.
-    return db
-      .select()
-      .from(messages)
-      .where(lineageMessageFilter(segments))
-      .orderBy(asc(messages.createdAt), asc(messages.id))
-      .all()
-      .map(parseMessage);
-  }
-  const ref = loadMessageBound(afterMessageId);
-  if (!ref) {
+  const start = resolveMessagesAfterBound(after);
+  if (start.kind === "vanished") {
     return [];
   }
-  // Same `(createdAt, id)` cursor as `countMessagesAfter` — rows sharing
-  // the reference's millisecond timestamp would otherwise be skipped.
+  // Secondary `asc(messages.id)` mirrors the bound's tie-breaker, so callers
+  // tracking `cutoffMessageId` across runs see a consistent ordering when
+  // multiple rows share a millisecond timestamp.
   return db
     .select()
     .from(messages)
-    .where(lineageMessagesAfterFilter(segments, ref))
+    .where(
+      start.kind === "all"
+        ? lineageMessageFilter(segments)
+        : lineageMessagesAfterFilter(segments, start.bound),
+    )
     .orderBy(asc(messages.createdAt), asc(messages.id))
     .all()
     .map(parseMessage);
@@ -4304,12 +4287,12 @@ export function deleteLastExchange(conversationId: string): number {
 
   // Collect attachment IDs linked to the messages being deleted so we can
   // scope orphan cleanup to only those candidates (not freshly uploaded ones).
-  const messageIds = db
-    .select({ id: messages.id })
+  const deletedRows = db
+    .select({ id: messages.id, createdAt: messages.createdAt })
     .from(messages)
     .where(condition)
-    .all()
-    .map((r) => r.id);
+    .all();
+  const messageIds = deletedRows.map((r) => r.id);
   const candidateAttachmentIds =
     messageIds.length > 0
       ? db
@@ -4356,6 +4339,17 @@ export function deleteLastExchange(conversationId: string): number {
     enqueueDeleteMessageLexical(deletedMessageId);
   }
 
+  // Notify `message-deleted` hooks for each removed row, as the
+  // single-message primitive does: undo removes the same tail a regenerate
+  // does, and a hook keeping a cursor on one of these rows needs its position.
+  for (const row of deletedRows) {
+    void runHook(HOOKS.MESSAGE_DELETED, {
+      conversationId,
+      messageId: row.id,
+      createdAt: row.createdAt,
+    } satisfies MessageDeletedInputContext);
+  }
+
   return deleted;
 }
 
@@ -4594,9 +4588,13 @@ export function deleteMessageById(
     .map((r) => r.attachmentId)
     .filter((id): id is string => id !== undefined);
 
-  // Look up the conversation before the transaction so we can recalculate lastMessageAt.
+  // Look up the conversation before the transaction so we can recalculate
+  // lastMessageAt, and the row's createdAt for the `message-deleted` hook.
   const msgRow = db
-    .select({ conversationId: messages.conversationId })
+    .select({
+      conversationId: messages.conversationId,
+      createdAt: messages.createdAt,
+    })
     .from(messages)
     .where(eq(messages.id, messageId))
     .get();
@@ -4652,6 +4650,16 @@ export function deleteMessageById(
   // not go through the conversation-level purge.
   if (msgRow) {
     enqueueDeleteMessageLexical(messageId);
+
+    // Notify `message-deleted` hooks (e.g. the memory plugin stamping a
+    // retrospective cursor that sat on this row). Fire-and-forget from this
+    // synchronous primitive, like `conversation-deleted`; the context carries
+    // the row's position because the row itself is gone.
+    void runHook(HOOKS.MESSAGE_DELETED, {
+      conversationId: msgRow.conversationId,
+      messageId,
+      createdAt: msgRow.createdAt,
+    } satisfies MessageDeletedInputContext);
   }
 
   return result;

package/src/persistence/conversation-lineage.ts

@@ -227,9 +227,17 @@ export function lineageMessagesAfterFilter(
 ): SQL {
   return and(
     lineageMessageFilter(segments),
-    or(
-      gt(messages.createdAt, after.createdAt),
-      and(eq(messages.createdAt, after.createdAt), gt(messages.id, after.id)),
-    ),
+    messagesAfterBoundFilter(after),
+  ) as SQL;
+}
+
+/**
+ * Predicate for rows strictly after a `(createdAt, id)` bound, with the id
+ * tie-breaker so rows sharing the bound's millisecond keep their order.
+ */
+export function messagesAfterBoundFilter(after: LineageBound): SQL {
+  return or(
+    gt(messages.createdAt, after.createdAt),
+    and(eq(messages.createdAt, after.createdAt), gt(messages.id, after.id)),
   ) as SQL;
 }

package/src/persistence/conversation-queries.ts

@@ -17,6 +17,7 @@ import {
   wrapUntrustedContent,
 } from "../security/untrusted-content.js";
 import { getLogger } from "../util/logger.js";
+import { safeStringSlice } from "../util/unicode.js";
 import { isLexicalBackfillComplete } from "./checkpoints.js";
 import { unseenAttentionStateConditions } from "./conversation-attention-store.js";
 import type { ConversationRow } from "./conversation-crud.js";
@@ -1443,8 +1444,7 @@ function buildExcerptFromText(
   if (!match) {
     // Neither the query nor any of its tokens is present (e.g. the lexical
     // index matched JSON structure instead); fall back to the text start.
-    return text
-      .slice(0, EXCERPT_WINDOW * 2)
+    return safeStringSlice(text, 0, EXCERPT_WINDOW * 2)
       .replace(/\s+/g, " ")
       .trim();
   }

package/src/persistence/conversation-title-placeholders.ts

@@ -0,0 +1,23 @@
+import { isMessageKey } from "../i18n/index.js";
+
+const REPLACEABLE_PATTERNS = [
+  /^Runtime:\s/,
+  /^New Conversation$/,
+  /^Untitled$/,
+  /^Untitled Conversation$/,
+  /^Generating title\.\.\.$/,
+];
+
+/**
+ * Check whether a title is a system-generated placeholder that can be
+ * replaced or omitted without discarding user-provided copy.
+ */
+export function isReplaceableTitle(title: string | null): boolean {
+  if (title == null || title.trim() === "") {
+    return true;
+  }
+  if (isMessageKey(title.trim())) {
+    return true;
+  }
+  return REPLACEABLE_PATTERNS.some((pattern) => pattern.test(title));
+}

package/src/persistence/conversation-title-service.ts

@@ -8,6 +8,7 @@
  */
 
 import { SEND_USER_MESSAGE_DELIVERED_ACK } from "../config/send-user-message-constants.js";
+import { MESSAGE_KEYS } from "../i18n/index.js";
 import {
   requestShortLabel,
   type ShortLabelTool,
@@ -24,8 +25,11 @@ import {
   type MessageRow,
   updateConversationTitle,
 } from "./conversation-crud.js";
+import { isReplaceableTitle } from "./conversation-title-placeholders.js";
 import { projectPersistedAssistantContent } from "./user-facing-content.js";
 
+export { isReplaceableTitle } from "./conversation-title-placeholders.js";
+
 const log = getLogger("conversation-title-service");
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -65,8 +69,8 @@ export interface TitleContext {
 
 // ── Placeholder / loading state ──────────────────────────────────────
 
-export const GENERATING_TITLE = "Generating title...";
-const UNTITLED_FALLBACK = "Untitled Conversation";
+export const GENERATING_TITLE = MESSAGE_KEYS.CONVERSATION_TITLE_GENERATING;
+const UNTITLED_FALLBACK = MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED;
 
 // ── `conversations.isAutoTitle` values ───────────────────────────────
 //
@@ -83,28 +87,6 @@ export const AUTO_TITLE_LLM = 1;
  */
 export const AUTO_TITLE_DETERMINISTIC = 2;
 
-// ── Replaceability check ─────────────────────────────────────────────
-
-const REPLACEABLE_PATTERNS = [
-  /^Runtime:\s/,
-  /^New Conversation$/,
-  /^Untitled$/,
-  /^Untitled Conversation$/,
-  /^Generating title\.\.\.$/,
-];
-
-/**
- * Check whether a title is a system-generated placeholder that can be
- * safely overwritten by auto-generated titles. Returns `false` for
- * user-provided custom titles.
- */
-export function isReplaceableTitle(title: string | null): boolean {
-  if (title == null || title.trim() === "") {
-    return true;
-  }
-  return REPLACEABLE_PATTERNS.some((pattern) => pattern.test(title));
-}
-
 /**
  * Whether auto-generation may overwrite the conversation's current title.
  * True for placeholder/system titles and for deterministic bootstrap titles
@@ -255,7 +237,7 @@ function settleForDeterministicTitle(
  * conversation creation (e.g. 5 new chats in quick succession) fires N
  * concurrent requests that can hit provider rate limits or contend for
  * API capacity, causing later calls to time out and fall back to
- * "Untitled Conversation".
+ * the untitled catalog key.
  *
  * A serial queue ensures at most one title-generation LLM call is
  * in-flight at a time. Each call is lightweight (~1–3 s for a ≤5-word
@@ -289,7 +271,7 @@ export function queueGenerateConversationTitle(
       // Replace loading placeholder with a retryable fallback.
       try {
         const conversation = getConversation(params.conversationId);
-        if (conversation && conversation.title === GENERATING_TITLE) {
+        if (conversation && isReplaceableTitle(conversation.title)) {
           const fallback =
             deriveFallbackTitle(params.context) ?? UNTITLED_FALLBACK;
           updateConversationTitle(
@@ -424,6 +406,7 @@ function buildTitleSystemPrompt(): string {
     "- Think: what would make a scannable sidebar label?",
     "- Do NOT echo back what the user asked you to do",
     "- Do NOT respond to the conversation content",
+    "- Write the title in the same language as the conversation content",
     "- Do NOT assess feasibility or comment on capabilities",
     "- If input is sparse or references external context, extract a topic from the words that ARE present (e.g. 'so about that t-shirt...' → 'T-Shirt Discussion'). Never describe the absence, emptiness, or insufficiency of context — titles like 'Missing Context', 'Unclear Request', 'No Topic' are forbidden",
   ].join("\n");

package/src/persistence/embeddings/qdrant-manager.ts

@@ -33,6 +33,116 @@ const SHUTDOWN_GRACE_MS = 5_000;
 const STDOUT_CAPTURE_LIMIT = 16_384;
 const STDERR_CAPTURE_LIMIT = 4_096;
 
+/**
+ * Which step of a local start failed. `install` covers the download, checksum
+ * and extraction of the binary; `spawn` the OS refusing to run it; `exited`
+ * the process dying before `/readyz` answered; `not_ready` the readiness
+ * deadline passing with the process still alive (or, in external mode, the
+ * remote instance never answering).
+ */
+export type QdrantStartFailureKind =
+  | "install"
+  | "spawn"
+  | "exited"
+  | "not_ready";
+
+/**
+ * A failed `QdrantManager.start()`. The message keeps the captured output for
+ * the log line; the fields carry the same facts in a form a reporter can use
+ * without parsing that message.
+ */
+export class QdrantStartError extends Error {
+  constructor(
+    message: string,
+    readonly kind: QdrantStartFailureKind,
+    readonly exitCode: number | null,
+    readonly stdout: string,
+    readonly stderr: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "QdrantStartError";
+  }
+}
+
+/**
+ * Budget for the `panic` string {@link describeQdrantStartFailure} emits, in
+ * the bytes the telemetry server counts: JSON with every code unit above 0x7E
+ * escaped as `\uXXXX` (see `jsonByteLength` in `telemetry-wire.generated.ts`).
+ * A quarter of `WATCHDOG_DETAIL_MAX_JSON_BYTES`, leaving the other fields and
+ * the event envelope far from the limit that silently drops the event.
+ */
+const PANIC_REPORT_MAX_JSON_BYTES = 1_024;
+
+/**
+ * Longest prefix of `text` whose server-side JSON size fits `maxBytes`. Each
+ * UTF-16 code unit above 0x7E costs six bytes (astral characters two units,
+ * so twelve); quotes, backslashes and control characters cost what
+ * `JSON.stringify` escapes them to. Counting characters instead would let a
+ * non-ASCII reason overshoot the budget six-fold.
+ */
+function truncateToJsonBytes(text: string, maxBytes: number): string {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i);
+    bytes += unit > 0x7e ? 6 : JSON.stringify(text[i]).length - 2;
+    if (bytes > maxBytes) {
+      return text.slice(0, i);
+    }
+  }
+  return text;
+}
+
+/** Qdrant's panic hook logs `Panic occurred <location>: <reason>` on stdout. */
+const PANIC_MARKER = "Panic occurred";
+
+/**
+ * Reduce a start failure to the metadata a `watchdog` telemetry event may
+ * carry: the failing step, the exit code, and Qdrant's own one-line reason.
+ *
+ * The reason is engine output, never conversation content, so it is in the
+ * same class as the SQLite `integrity_check` strings `db-integrity-sample.ts`
+ * already reports. The one thing in it that is not pure engine text is the
+ * absolute data directory, which is swapped for a placeholder. The panic hook
+ * prints the reason after the backtrace, so it is everything from the last
+ * marker on; when Qdrant died without panicking (a port collision logs a plain
+ * error) the last stdout line is the best available explanation. Capped by
+ * the server's own byte measure well inside the detail budget. Anything that is not a
+ * {@link QdrantStartError} reports as `unknown`, so a new throw site can never
+ * silently drop the event.
+ */
+export function describeQdrantStartFailure(
+  err: unknown,
+  dataDir: string = getDataDir(),
+): {
+  kind: QdrantStartFailureKind | "unknown";
+  exit_code: number | null;
+  panic: string | null;
+} {
+  if (!(err instanceof QdrantStartError)) {
+    return { kind: "unknown", exit_code: null, panic: null };
+  }
+  const stdout = err.stdout.trim();
+  let reason: string | null = null;
+  if (stdout) {
+    const marker = stdout.lastIndexOf(PANIC_MARKER);
+    reason =
+      marker >= 0
+        ? stdout.slice(marker)
+        : (stdout
+            .split("\n")
+            .filter((line) => line.trim())
+            .at(-1) ?? null);
+  }
+  if (reason) {
+    reason = truncateToJsonBytes(
+      reason.split(dataDir).join("<data>"),
+      PANIC_REPORT_MAX_JSON_BYTES,
+    );
+  }
+  return { kind: err.kind, exit_code: err.exitCode, panic: reason };
+}
+
 export function resolveQdrantReleaseAsset(
   os: NodeJS.Platform,
   cpu: string,
@@ -144,7 +254,11 @@ export class QdrantManager {
 
     const binaryPath = this.getBinaryPath();
     if (!existsSync(binaryPath)) {
-      await this.installBinary(binaryPath);
+      try {
+        await this.installBinary(binaryPath);
+      } catch (err) {
+        throw this.startError(err, "install");
+      }
     }
 
     const spawnPath = this.ensureVellumSymlink(binaryPath);
@@ -154,21 +268,26 @@ export class QdrantManager {
       "Starting Qdrant",
     );
 
-    const proc = Bun.spawn({
-      cmd: [spawnPath],
-      windowsHide: true,
-      env: {
-        ...process.env,
-        QDRANT__SERVICE__HOST: this.host,
-        QDRANT__SERVICE__HTTP_PORT: String(this.port),
-        QDRANT__SERVICE__GRPC_PORT: "0", // disable gRPC
-        QDRANT__TELEMETRY_DISABLED: "true",
-        QDRANT__STORAGE__STORAGE_PATH: this.storagePath,
-        QDRANT__LOG_LEVEL: "WARN",
-      },
-      stdout: "pipe",
-      stderr: "pipe",
-    });
+    let proc: Subprocess<"ignore", "pipe", "pipe">;
+    try {
+      proc = Bun.spawn({
+        cmd: [spawnPath],
+        windowsHide: true,
+        env: {
+          ...process.env,
+          QDRANT__SERVICE__HOST: this.host,
+          QDRANT__SERVICE__HTTP_PORT: String(this.port),
+          QDRANT__SERVICE__GRPC_PORT: "0", // disable gRPC
+          QDRANT__TELEMETRY_DISABLED: "true",
+          QDRANT__STORAGE__STORAGE_PATH: this.storagePath,
+          QDRANT__LOG_LEVEL: "WARN",
+        },
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+    } catch (err) {
+      throw this.startError(err, "spawn");
+    }
     this.process = proc;
     this.drainOutputFrom(proc.stdout, proc.stderr);
 
@@ -311,6 +430,24 @@ export class QdrantManager {
     );
   }
 
+  /**
+   * Wrap a failure from a start step in a {@link QdrantStartError}. Errors the
+   * manager already classified pass through untouched.
+   */
+  private startError(err: unknown, kind: QdrantStartFailureKind): Error {
+    if (err instanceof QdrantStartError) {
+      return err;
+    }
+    return new QdrantStartError(
+      err instanceof Error ? err.message : String(err),
+      kind,
+      null,
+      this.stdoutBuffer,
+      this.stderrBuffer,
+      { cause: err },
+    );
+  }
+
   private async waitForReady(): Promise<void> {
     const start = Date.now();
     // Build a single exited-promise once so each race reuses the same handle.
@@ -327,9 +464,13 @@ export class QdrantManager {
 
     const throwOnExit = async (code: number): Promise<never> => {
       await this.outputDrained;
-      throw new Error(
+      throw new QdrantStartError(
         `Qdrant process exited with code ${code} before becoming ready` +
           this.formatCapturedOutput(),
+        "exited",
+        code,
+        this.stdoutBuffer,
+        this.stderrBuffer,
       );
     };
 
@@ -363,9 +504,13 @@ export class QdrantManager {
         await throwOnExit(sleepOutcome.code);
       }
     }
-    throw new Error(
+    throw new QdrantStartError(
       `Qdrant did not become ready within ${this.readyzTimeoutMs}ms at ${this.url}` +
         this.formatCapturedOutput(),
+      "not_ready",
+      null,
+      this.stdoutBuffer,
+      this.stderrBuffer,
     );
   }