@vellumai/assistant 0.3.4 → 0.3.6

package/src/messaging/thread-summarizer.ts

@@ -1,12 +1,11 @@
-import Anthropic from '@anthropic-ai/sdk';
-import { getConfig } from '../config/loader.js';
+import { getConfiguredProvider, createTimeout, extractToolUse, userMessage } from '../providers/provider-send-message.js';
 import { getLogger } from '../util/logger.js';
 import { truncate } from '../util/truncate.js';
 import type { ThreadMessage, ThreadSummary } from './types.js';
 
 const log = getLogger('thread-summarizer');
 
-const SUMMARIZATION_MODEL = 'claude-haiku-4-5-20251001';
+const SUMMARIZATION_MODEL_INTENT = 'latency-optimized' as const;
 const SUMMARIZATION_TIMEOUT_MS = 20_000;
 const DEFAULT_MAX_TOKENS = 4000;
 const CHARS_PER_TOKEN = 4;
@@ -189,78 +188,71 @@ async function summarizeWithLLM(
   messages: ThreadMessage[],
   maxTokens: number,
 ): Promise<ThreadSummary> {
-  const config = getConfig();
-  const apiKey = config.apiKeys.anthropic ?? process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    log.warn('No Anthropic API key available for thread summarization, returning basic summary');
+  const provider = getConfiguredProvider();
+  if (!provider) {
+    log.warn('Configured provider unavailable for thread summarization, returning basic summary');
     return buildFallbackSummary(messages);
   }
 
-  const truncated = truncateMessages(messages, maxTokens);
-  const transcript = formatTranscript(truncated);
+  const truncatedMsgs = truncateMessages(messages, maxTokens);
+  const transcript = formatTranscript(truncatedMsgs);
 
   try {
-    const client = new Anthropic({ apiKey });
-    const abortController = new AbortController();
-    let timer: ReturnType<typeof setTimeout>;
-    const apiCall = client.messages.create({
-      model: SUMMARIZATION_MODEL,
-      max_tokens: 1024,
-      system: SYSTEM_PROMPT,
-      tools: [STORE_SUMMARY_TOOL],
-      tool_choice: { type: 'tool' as const, name: 'store_thread_summary' },
-      messages: [{
-        role: 'user' as const,
-        content: `Summarize this conversation thread (${messages.length} messages):\n\n${transcript}`,
-      }],
-    }, { signal: abortController.signal });
-
-    // Swallow the abort rejection that fires when the timeout wins the race
-    apiCall.catch(() => {});
-    const response = await Promise.race([
-      apiCall.finally(() => clearTimeout(timer)),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(() => {
-          abortController.abort();
-          reject(new Error('Thread summarization LLM timeout'));
-        }, SUMMARIZATION_TIMEOUT_MS);
-      }),
-    ]);
-
-    const toolBlock = response.content.find((b) => b.type === 'tool_use');
-    if (!toolBlock || toolBlock.type !== 'tool_use') {
-      log.warn('No tool_use block in summarization response, returning fallback');
-      return buildFallbackSummary(messages);
-    }
+    const { signal, cleanup } = createTimeout(SUMMARIZATION_TIMEOUT_MS);
+
+    try {
+      const response = await provider.sendMessage(
+        [userMessage(`Summarize this conversation thread (${messages.length} messages):\n\n${transcript}`)],
+        [STORE_SUMMARY_TOOL],
+        SYSTEM_PROMPT,
+        {
+          config: {
+            modelIntent: SUMMARIZATION_MODEL_INTENT,
+            max_tokens: 1024,
+            tool_choice: { type: 'tool' as const, name: 'store_thread_summary' },
+          },
+          signal,
+        },
+      );
+      cleanup();
 
-    const input = toolBlock.input as {
-      summary?: string;
-      participants?: Array<{ name: string; role?: string }>;
-      openQuestions?: string[];
-      lastAction?: string;
-      sentiment?: string;
-    };
-
-    const validSentiments = new Set(['positive', 'neutral', 'negative', 'mixed']);
-    const sentiment = validSentiments.has(input.sentiment ?? '')
-      ? (input.sentiment as ThreadSummary['sentiment'])
-      : 'neutral';
-
-    return {
-      summary: truncate(String(input.summary ?? ''), 2000, ''),
-      participants: Array.isArray(input.participants)
-        ? input.participants.map((p) => ({
-            name: String(p.name),
-            ...(p.role ? { role: String(p.role) } : {}),
-          }))
-        : extractParticipants(messages),
-      openQuestions: Array.isArray(input.openQuestions)
-        ? input.openQuestions.map((q) => String(q))
-        : [],
-      lastAction: truncate(String(input.lastAction ?? ''), 500, ''),
-      sentiment,
-      messageCount: messages.length,
-    };
+      const toolBlock = extractToolUse(response);
+      if (!toolBlock) {
+        log.warn('No tool_use block in summarization response, returning fallback');
+        return buildFallbackSummary(messages);
+      }
+
+      const input = toolBlock.input as {
+        summary?: string;
+        participants?: Array<{ name: string; role?: string }>;
+        openQuestions?: string[];
+        lastAction?: string;
+        sentiment?: string;
+      };
+
+      const validSentiments = new Set(['positive', 'neutral', 'negative', 'mixed']);
+      const sentiment = validSentiments.has(input.sentiment ?? '')
+        ? (input.sentiment as ThreadSummary['sentiment'])
+        : 'neutral';
+
+      return {
+        summary: truncate(String(input.summary ?? ''), 2000, ''),
+        participants: Array.isArray(input.participants)
+          ? input.participants.map((p) => ({
+              name: String(p.name),
+              ...(p.role ? { role: String(p.role) } : {}),
+            }))
+          : extractParticipants(messages),
+        openQuestions: Array.isArray(input.openQuestions)
+          ? input.openQuestions.map((q) => String(q))
+          : [],
+        lastAction: truncate(String(input.lastAction ?? ''), 500, ''),
+        sentiment,
+        messageCount: messages.length,
+      };
+    } finally {
+      cleanup();
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.warn({ err: message }, 'Thread summarization LLM call failed, returning fallback');

package/src/messaging/triage-engine.ts

@@ -2,16 +2,15 @@
  * Channel-agnostic message triage engine.
  *
  * Classifies an inbound message by combining sender context from the
- * contact graph, matching action playbooks, and an LLM call (Haiku)
+ * contact graph, matching action playbooks, and an LLM call
  * for final classification. Results are persisted to the triageResults
  * table for accuracy review.
  */
 
-import Anthropic from '@anthropic-ai/sdk';
+import { getConfiguredProvider, createTimeout, extractToolUse, userMessage } from '../providers/provider-send-message.js';
 import { truncate } from '../util/truncate.js';
 import { v4 as uuid } from 'uuid';
 import { and, eq, isNull, desc } from 'drizzle-orm';
-import { getConfig } from '../config/loader.js';
 import { getLogger } from '../util/logger.js';
 import { getDb } from '../memory/db.js';
 import { memoryItems, triageResults } from '../memory/schema.js';
@@ -24,7 +23,7 @@ import { DEFAULT_TRIAGE_CATEGORIES } from './types.js';
 
 const log = getLogger('triage-engine');
 
-const TRIAGE_MODEL = 'claude-haiku-4-5-20251001';
+const TRIAGE_MODEL_INTENT = 'latency-optimized' as const;
 const TRIAGE_CLASSIFICATION_TIMEOUT_MS = 15_000;
 
 // ── Playbook fetching ────────────────────────────────────────────────
@@ -189,10 +188,9 @@ export async function triageMessage(
   const playbookMatches = fetchMatchingPlaybooks(message.channel, scopeId);
 
   // Step 3: Classify with LLM
-  const config = getConfig();
-  const apiKey = config.apiKeys.anthropic ?? process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    log.warn('No Anthropic API key available for triage classification, returning fallback');
+  const provider = getConfiguredProvider();
+  if (!provider) {
+    log.warn('Configured provider unavailable for triage classification, returning fallback');
     const result = buildFallbackResult();
     persistTriageResult(message, result, playbookMatches);
     return result;
@@ -200,7 +198,7 @@ export async function triageMessage(
 
   let result: TriageResult;
   try {
-    result = await classifyWithLLM(message, contact, playbookMatches, apiKey);
+    result = await classifyWithLLM(message, contact, playbookMatches);
   } catch (err) {
     const errMsg = err instanceof Error ? err.message : String(err);
     log.warn({ err: errMsg }, 'Triage LLM call failed, returning fallback');
@@ -217,77 +215,70 @@ async function classifyWithLLM(
   message: InboundMessage,
   contact: ContactWithChannels | null,
   playbookMatches: PlaybookMatch[],
-  apiKey: string,
 ): Promise<TriageResult> {
-  const client = new Anthropic({ apiKey });
-  const abortController = new AbortController();
-  let timer: ReturnType<typeof setTimeout>;
+  const provider = getConfiguredProvider()!;
+  const { signal, cleanup } = createTimeout(TRIAGE_CLASSIFICATION_TIMEOUT_MS);
 
   const systemPrompt = buildSystemPrompt(contact, playbookMatches);
   const userPrompt = buildUserPrompt(message);
 
-  const apiCall = client.messages.create({
-    model: TRIAGE_MODEL,
-    max_tokens: 1024,
-    system: systemPrompt,
-    tools: [STORE_TRIAGE_TOOL],
-    tool_choice: { type: 'tool' as const, name: 'store_triage_result' },
-    messages: [{
-      role: 'user' as const,
-      content: userPrompt,
-    }],
-  }, { signal: abortController.signal });
-
-  // Swallow the abort rejection that fires when the timeout wins the race
-  apiCall.catch(() => {});
-  const response = await Promise.race([
-    apiCall.finally(() => clearTimeout(timer)),
-    new Promise<never>((_, reject) => {
-      timer = setTimeout(() => {
-        abortController.abort();
-        reject(new Error('Triage classification LLM timeout'));
-      }, TRIAGE_CLASSIFICATION_TIMEOUT_MS);
-    }),
-  ]);
-
-  const toolBlock = response.content.find((b) => b.type === 'tool_use');
-  if (!toolBlock || toolBlock.type !== 'tool_use') {
-    log.warn('No tool_use block in triage response, returning fallback');
-    return buildFallbackResult();
-  }
-
-  const input = toolBlock.input as {
-    category?: string;
-    confidence?: number;
-    suggestedAction?: string;
-    matchedPlaybookTriggers?: string[];
-  };
+  try {
+    const response = await provider.sendMessage(
+      [userMessage(userPrompt)],
+      [STORE_TRIAGE_TOOL],
+      systemPrompt,
+      {
+        config: {
+          modelIntent: TRIAGE_MODEL_INTENT,
+          max_tokens: 1024,
+          tool_choice: { type: 'tool' as const, name: 'store_triage_result' },
+        },
+        signal,
+      },
+    );
+    cleanup();
 
-  const matchedTriggers = new Set(
-    Array.isArray(input.matchedPlaybookTriggers) ? input.matchedPlaybookTriggers : [],
-  );
+    const toolBlock = extractToolUse(response);
+    if (!toolBlock) {
+      log.warn('No tool_use block in triage response, returning fallback');
+      return buildFallbackResult();
+    }
 
-  // Map LLM-identified triggers back to the full playbook data
-  const matchedPlaybooks = playbookMatches
-    .filter(({ playbook }) => matchedTriggers.has(playbook.trigger))
-    .map(({ playbook }) => ({
-      trigger: playbook.trigger,
-      action: playbook.action,
-      autonomyLevel: playbook.autonomyLevel,
-    }));
+    const input = toolBlock.input as {
+      category?: string;
+      confidence?: number;
+      suggestedAction?: string;
+      matchedPlaybookTriggers?: string[];
+    };
 
-  const confidence = typeof input.confidence === 'number'
-    ? Math.max(0, Math.min(1, input.confidence))
-    : 0.5;
+    const matchedTriggers = new Set(
+      Array.isArray(input.matchedPlaybookTriggers) ? input.matchedPlaybookTriggers : [],
+    );
 
-  return {
-    category: typeof input.category === 'string' ? input.category : 'needs_response',
-    confidence,
-    suggestedAction: typeof input.suggestedAction === 'string'
-      ? truncate(input.suggestedAction, 500, '')
-      : 'Review manually',
-    matchedPlaybooks,
-  };
+    // Map LLM-identified triggers back to the full playbook data
+    const matchedPlaybooks = playbookMatches
+      .filter(({ playbook }) => matchedTriggers.has(playbook.trigger))
+      .map(({ playbook }) => ({
+        trigger: playbook.trigger,
+        action: playbook.action,
+        autonomyLevel: playbook.autonomyLevel,
+      }));
+
+    const confidence = typeof input.confidence === 'number'
+      ? Math.max(0, Math.min(1, input.confidence))
+      : 0.5;
+
+    return {
+      category: typeof input.category === 'string' ? input.category : 'needs_response',
+      confidence,
+      suggestedAction: typeof input.suggestedAction === 'string'
+        ? truncate(input.suggestedAction, 500, '')
+        : 'Review manually',
+      matchedPlaybooks,
+    };
+  } finally {
+    cleanup();
+  }
 }
 
 // ── Persistence ─────────────────────────────────────────────────────

package/src/migrations/config-merge.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { isPlainObject } from '../util/object.js';
+import { migrationLog } from './log.js';
+
+/**
+ * When migratePath skips config.json because the workspace copy already
+ * exists, the legacy root config may still contain keys (e.g. slackWebhookUrl)
+ * that were never written to the workspace config. This merges any missing
+ * top-level keys from the legacy file into the workspace file so they are
+ * not silently lost during upgrade.
+ */
+export function mergeSkippedConfigKeys(legacyPath: string, workspacePath: string): void {
+  if (!existsSync(legacyPath) || !existsSync(workspacePath)) return;
+
+  let legacy: Record<string, unknown>;
+  let workspace: Record<string, unknown>;
+  try {
+    const legacyRaw = JSON.parse(readFileSync(legacyPath, 'utf-8'));
+    const workspaceRaw = JSON.parse(readFileSync(workspacePath, 'utf-8'));
+    if (!isPlainObject(legacyRaw) || !isPlainObject(workspaceRaw)) return;
+    legacy = legacyRaw;
+    workspace = workspaceRaw;
+  } catch {
+    return; // malformed JSON — skip silently
+  }
+
+  const merged: string[] = [];
+  for (const key of Object.keys(legacy)) {
+    if (!(key in workspace)) {
+      workspace[key] = legacy[key];
+      merged.push(key);
+    }
+  }
+
+  if (merged.length > 0) {
+    try {
+      writeFileSync(workspacePath, JSON.stringify(workspace, null, 2) + '\n');
+      // Remove merged keys from legacy config so they are not resurrected
+      // if a user later deletes them from the workspace config.
+      for (const key of merged) {
+        delete legacy[key];
+      }
+      if (Object.keys(legacy).length === 0) {
+        unlinkSync(legacyPath);
+      } else {
+        writeFileSync(legacyPath, JSON.stringify(legacy, null, 2) + '\n');
+      }
+      migrationLog('info', 'Merged legacy config keys into workspace config', { keys: merged });
+    } catch (err) {
+      migrationLog('warn', 'Failed to merge legacy config keys', { err: String(err), keys: merged });
+    }
+  }
+}

package/src/migrations/data-layout.ts

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { getRootDir } from '../util/platform.js';
+import { migrationLog } from './log.js';
+
+/**
+ * Migrate files from the old flat ~/.vellum layout to the new structured
+ * layout with data/ and protected/ subdirectories.
+ *
+ * Idempotent: skips items that have already been migrated.
+ * Uses renameSync for atomic moves (same filesystem).
+ */
+export function migrateToDataLayout(): void {
+  const root = getRootDir();
+  const data = join(root, 'data');
+
+  if (!existsSync(root)) return;
+
+  function migrateItem(oldPath: string, newPath: string): void {
+    if (!existsSync(oldPath)) return;
+    if (existsSync(newPath)) return;
+    try {
+      const newDir = dirname(newPath);
+      if (!existsSync(newDir)) {
+        mkdirSync(newDir, { recursive: true });
+      }
+      renameSync(oldPath, newPath);
+      migrationLog('info', 'Migrated path', { from: oldPath, to: newPath });
+    } catch (err) {
+      migrationLog('warn', 'Failed to migrate path', { err: String(err), from: oldPath, to: newPath });
+    }
+  }
+
+  // DB: ~/.vellum/data/assistant.db → ~/.vellum/data/db/assistant.db
+  migrateItem(join(data, 'assistant.db'), join(data, 'db', 'assistant.db'));
+  migrateItem(join(data, 'assistant.db-wal'), join(data, 'db', 'assistant.db-wal'));
+  migrateItem(join(data, 'assistant.db-shm'), join(data, 'db', 'assistant.db-shm'));
+
+  // Qdrant PID: ~/.vellum/qdrant.pid → ~/.vellum/data/qdrant/qdrant.pid
+  migrateItem(join(root, 'qdrant.pid'), join(data, 'qdrant', 'qdrant.pid'));
+
+  // Qdrant binary: ~/.vellum/bin/ → ~/.vellum/data/qdrant/bin/
+  migrateItem(join(root, 'bin'), join(data, 'qdrant', 'bin'));
+
+  // Logs: ~/.vellum/logs/ → ~/.vellum/data/logs/
+  migrateItem(join(root, 'logs'), join(data, 'logs'));
+
+  // Memory: ~/.vellum/memory/ → ~/.vellum/data/memory/
+  migrateItem(join(root, 'memory'), join(data, 'memory'));
+
+  // Apps: ~/.vellum/apps/ → ~/.vellum/data/apps/
+  migrateItem(join(root, 'apps'), join(data, 'apps'));
+
+  // Browser auth: ~/.vellum/browser-auth/ → ~/.vellum/data/browser-auth/
+  migrateItem(join(root, 'browser-auth'), join(data, 'browser-auth'));
+
+  // Browser profile: ~/.vellum/browser-profile/ → ~/.vellum/data/browser-profile/
+  migrateItem(join(root, 'browser-profile'), join(data, 'browser-profile'));
+
+  // History: ~/.vellum/history → ~/.vellum/data/history
+  migrateItem(join(root, 'history'), join(data, 'history'));
+
+  // Protected files: ~/.vellum/X → ~/.vellum/protected/X
+  const protectedDir = join(root, 'protected');
+  migrateItem(join(root, 'trust.json'), join(protectedDir, 'trust.json'));
+  migrateItem(join(root, 'keys.enc'), join(protectedDir, 'keys.enc'));
+  migrateItem(join(root, 'secret-allowlist.json'), join(protectedDir, 'secret-allowlist.json'));
+}

package/src/migrations/data-merge.ts

@@ -0,0 +1,33 @@
+import { existsSync, readdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { migrationLog } from './log.js';
+
+/**
+ * When migratePath skips the data directory because workspace/data already
+ * exists (e.g. the user's project had a data/ folder that was extracted from
+ * sandbox/fs), the legacy data directory may still contain internal state
+ * subdirectories (db/, logs/, sandbox/, etc.) that need to be preserved.
+ * This merges any missing entries from the legacy data path into workspace/data.
+ */
+export function mergeLegacyDataEntries(legacyDir: string, workspaceDir: string): void {
+  if (!existsSync(legacyDir) || !existsSync(workspaceDir)) return;
+
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = readdirSync(legacyDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const src = join(legacyDir, entry.name);
+    const dest = join(workspaceDir, entry.name);
+    if (existsSync(dest)) continue; // already present in workspace
+    try {
+      renameSync(src, dest);
+      migrationLog('info', 'Merged legacy data entry into workspace', { from: src, to: dest });
+    } catch (err) {
+      migrationLog('warn', 'Failed to merge legacy data entry', { err: String(err), from: src, to: dest });
+    }
+  }
+}

package/src/migrations/hooks-merge.ts

@@ -0,0 +1,90 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { isPlainObject } from '../util/object.js';
+import { migrationLog } from './log.js';
+
+/**
+ * Merge missing hook entries from a legacy hooks/config.json into the
+ * workspace hooks/config.json. Only adds hooks that don't already exist
+ * in the workspace config so user changes are never overwritten.
+ */
+export function mergeHooksConfig(legacyPath: string, workspacePath: string): void {
+  let legacy: Record<string, unknown>;
+  let workspace: Record<string, unknown>;
+  try {
+    const legacyRaw = JSON.parse(readFileSync(legacyPath, 'utf-8'));
+    const workspaceRaw = JSON.parse(readFileSync(workspacePath, 'utf-8'));
+    if (!isPlainObject(legacyRaw) || !isPlainObject(workspaceRaw)) return;
+    legacy = legacyRaw;
+    workspace = workspaceRaw;
+  } catch {
+    return;
+  }
+
+  const legacyHooks = legacy.hooks;
+  const wsHooks = workspace.hooks;
+  if (!isPlainObject(legacyHooks) || !isPlainObject(wsHooks)) return;
+
+  const merged: string[] = [];
+  for (const hookName of Object.keys(legacyHooks)) {
+    if (!(hookName in wsHooks)) {
+      wsHooks[hookName] = legacyHooks[hookName];
+      merged.push(hookName);
+    }
+  }
+
+  if (merged.length > 0) {
+    try {
+      writeFileSync(workspacePath, JSON.stringify(workspace, null, 2) + '\n');
+      // Remove merged hooks from legacy config to prevent resurrection
+      for (const hookName of merged) {
+        delete legacyHooks[hookName];
+      }
+      if (Object.keys(legacyHooks).length === 0) {
+        unlinkSync(legacyPath);
+      } else {
+        writeFileSync(legacyPath, JSON.stringify(legacy, null, 2) + '\n');
+      }
+      migrationLog('info', 'Merged legacy hooks config entries into workspace', { hooks: merged });
+    } catch (err) {
+      migrationLog('warn', 'Failed to merge legacy hooks config', { err: String(err), hooks: merged });
+    }
+  }
+}
+
+/**
+ * When migratePath skips the hooks directory because the workspace copy
+ * already exists (e.g. pre-created by ensureDataDir), the legacy hooks
+ * directory may still contain individual hook files/subdirectories that
+ * were never moved. This merges any missing entries from the legacy
+ * path into the workspace hooks path so they are not silently lost.
+ */
+export function mergeLegacyHooks(legacyDir: string, workspaceDir: string): void {
+  if (!existsSync(legacyDir) || !existsSync(workspaceDir)) return;
+
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = readdirSync(legacyDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const src = join(legacyDir, entry.name);
+    const dest = join(workspaceDir, entry.name);
+    if (existsSync(dest)) {
+      // config.json needs a merge rather than a skip — the legacy file may
+      // contain hook enabled/settings entries that the workspace copy lacks.
+      if (entry.name === 'config.json') {
+        mergeHooksConfig(src, dest);
+      }
+      continue;
+    }
+    try {
+      renameSync(src, dest);
+      migrationLog('info', 'Merged legacy hook into workspace', { from: src, to: dest });
+    } catch (err) {
+      migrationLog('warn', 'Failed to merge legacy hook', { err: String(err), from: src, to: dest });
+    }
+  }
+}

package/src/migrations/index.ts

@@ -0,0 +1,6 @@
+export { migrateToDataLayout } from './data-layout.js';
+export { migrateToWorkspaceLayout, migratePath } from './workspace-layout.js';
+export { mergeSkippedConfigKeys } from './config-merge.js';
+export { mergeLegacyHooks, mergeHooksConfig } from './hooks-merge.js';
+export { mergeLegacySkills } from './skills-merge.js';
+export { mergeLegacyDataEntries } from './data-merge.js';

package/src/migrations/log.ts

@@ -0,0 +1,23 @@
+import pino from 'pino';
+import { logSerializers } from '../util/log-redact.js';
+
+/**
+ * Standalone pino instance for migration code. This must NOT use getLogger()
+ * because that triggers ensureDataDir(), which pre-creates workspace
+ * destination directories and causes migration moves to no-op.
+ *
+ * Writes to stderr only — no log files that might not exist yet.
+ */
+const migrationLogger: pino.Logger = pino(
+  { name: 'migration', level: 'info', serializers: logSerializers },
+  pino.destination(2),
+);
+
+export function migrationLog(level: 'info' | 'warn' | 'debug', msg: string, data?: Record<string, unknown>): void {
+  if (level === 'debug') return;
+  if (data) {
+    migrationLogger[level](data, msg);
+  } else {
+    migrationLogger[level](msg);
+  }
+}

package/src/migrations/skills-merge.ts

@@ -0,0 +1,33 @@
+import { existsSync, readdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { migrationLog } from './log.js';
+
+/**
+ * When migratePath skips the skills directory because the workspace copy
+ * already exists (e.g. pre-created by ensureDataDir), the legacy skills
+ * directory may still contain individual skill subdirectories that were
+ * never moved. This merges any missing skill subdirectories from the
+ * legacy path into the workspace skills path so they are not stranded.
+ */
+export function mergeLegacySkills(legacyDir: string, workspaceDir: string): void {
+  if (!existsSync(legacyDir) || !existsSync(workspaceDir)) return;
+
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = readdirSync(legacyDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const src = join(legacyDir, entry.name);
+    const dest = join(workspaceDir, entry.name);
+    if (existsSync(dest)) continue; // already present in workspace
+    try {
+      renameSync(src, dest);
+      migrationLog('info', 'Merged legacy skill into workspace', { from: src, to: dest });
+    } catch (err) {
+      migrationLog('warn', 'Failed to merge legacy skill', { err: String(err), from: src, to: dest });
+    }
+  }
+}