@vellumai/assistant 0.5.6 → 0.5.7

package/src/security/keychain-broker-client.ts

@@ -24,9 +24,10 @@ import { getRootDir } from "../util/platform.js";
 const log = getLogger("keychain-broker-client");
 
 const REQUEST_TIMEOUT_MS = 5_000;
+const CONNECT_TIMEOUT_MS = 3_000;
 
-/** Cooldown periods (ms) after consecutive connection failures: 30s, 60s, 2min, 5min, then cap at 5min. */
-const RECONNECT_COOLDOWN_MS = [30_000, 60_000, 120_000, 300_000];
+/** Cooldown periods (ms) after consecutive connection failures: 5s, 15s, 30s, 60s, 5min, then cap at 5min. */
+const RECONNECT_COOLDOWN_MS = [5_000, 15_000, 30_000, 60_000, 300_000];
 
 // ---------------------------------------------------------------------------
 // Types
@@ -191,7 +192,13 @@ export function createBrokerClient(): KeychainBrokerClient {
 
       const sock = createConnection({ path: socketPath });
 
+      const connectTimer = setTimeout(() => {
+        sock.destroy();
+        reject(new Error("Connect timeout"));
+      }, CONNECT_TIMEOUT_MS);
+
       sock.on("connect", () => {
+        clearTimeout(connectTimer);
         socket = sock;
         consecutiveFailures = 0;
         unavailableSince = null;
@@ -199,6 +206,7 @@ export function createBrokerClient(): KeychainBrokerClient {
       });
 
       sock.on("error", (err) => {
+        clearTimeout(connectTimer);
         log.warn({ err }, "Keychain broker socket error");
         cleanupSocket();
         reject(err);

package/src/security/secure-keys.ts

@@ -1,15 +1,17 @@
 /**
- * Unified secure key storage — single-writer routing through CredentialBackend
+ * Unified secure key storage — single-backend routing through CredentialBackend
  * adapters.
  *
- * Backend selection (`resolveBackend`) is the single decision point:
- *   - Containerized (IS_CONTAINERIZED + CES_CREDENTIAL_URL set): CES HTTP client.
- *   - Production (VELLUM_DEV unset or "0"): keychain backend when available.
- *   - Dev mode (VELLUM_DEV=1): encrypted file store always.
+ * Backend selection (`resolveBackendAsync`) is the single async decision point:
+ *   1. CES RPC (primary) — injected via `setCesClient()`: delegates credential
+ *      operations to the CES process over stdio RPC. This is the default path
+ *      for all local modes (desktop app, dev, CLI).
+ *   2. CES HTTP — containerized mode (IS_CONTAINERIZED + CES_CREDENTIAL_URL):
+ *      delegates to the CES sidecar over HTTP. Used in Docker/managed mode.
+ *   3. Encrypted file store (fallback) — used when CES is unavailable.
  *
- * Writes go to exactly one backend (no dual-writing). Reads in keychain mode
- * fall back to the encrypted store for keys that haven't been migrated yet.
- * Deletes clean up both stores regardless of mode.
+ * All operations (reads, writes, lists, deletes) go to exactly one backend.
+ * There are no cross-backend fallbacks or merges.
  */
 
 import type {
@@ -19,13 +21,12 @@ import type {
 
 import providerEnvVarsRegistry from "../../../meta/provider-env-vars.json" with { type: "json" };
 import { getIsContainerized } from "../config/env-registry.js";
+import type { CesClient } from "../credential-execution/client.js";
 import { getLogger } from "../util/logger.js";
 import { createCesCredentialBackend } from "./ces-credential-client.js";
+import { CesRpcCredentialBackend } from "./ces-rpc-credential-backend.js";
 import type { CredentialBackend, DeleteResult } from "./credential-backend.js";
-import {
-  createEncryptedStoreBackend,
-  createKeychainBackend,
-} from "./credential-backend.js";
+import { createEncryptedStoreBackend } from "./credential-backend.js";
 
 export type { DeleteResult } from "./credential-backend.js";
 
@@ -36,15 +37,24 @@ export type { DeleteResult } from "./credential-backend.js";
  */
 export type { SecureKeyBackend, SecureKeyDeleteResult };
 
+export interface SecureKeyResult {
+  value: string | undefined;
+  unreachable: boolean;
+}
+
 const log = getLogger("secure-keys");
 
-let _keychain: CredentialBackend | undefined;
+let _cesClient: CesClient | undefined;
 let _encryptedStore: CredentialBackend | undefined;
 let _resolvedBackend: CredentialBackend | undefined;
+let _resolvePromise: Promise<CredentialBackend> | undefined;
 
-function getKeychainBackend(): CredentialBackend {
-  if (!_keychain) _keychain = createKeychainBackend();
-  return _keychain;
+/** Inject a CES RPC client for credential routing. Resets the resolved backend. */
+export function setCesClient(client: CesClient | undefined): void {
+  _cesClient = client;
+  // Reset resolved backend so next call picks up CES
+  _resolvedBackend = undefined;
+  _resolvePromise = undefined;
 }
 
 function getEncryptedStoreBackend(): CredentialBackend {
@@ -53,101 +63,96 @@ function getEncryptedStoreBackend(): CredentialBackend {
 }
 
 /**
- * Resolve the primary credential backend for this process.
+ * Resolve the primary credential backend for this process (async).
  *
  * Priority:
- *   1. Containerized + CES_CREDENTIAL_URL → CES HTTP client (skip keychain
- *      and encrypted store entirely — the sidecar owns credential storage).
- *   2. Production (VELLUM_DEV unset or "0") → keychain when available.
- *   3. Dev mode (VELLUM_DEV=1) → encrypted file store always.
+ *   1. CES RPC client → primary path for all local modes.
+ *   2. Containerized + CES_CREDENTIAL_URL → CES HTTP client (Docker/managed).
+ *   3. Encrypted file store → fallback when CES is unavailable.
  *
  * Once resolved, the backend does not change during the process lifetime.
  * Call `_resetBackend()` in tests to clear the cached resolution.
  */
-function resolveBackend(): CredentialBackend {
-  if (!_resolvedBackend) {
-    if (getIsContainerized() && process.env.CES_CREDENTIAL_URL) {
-      const ces = createCesCredentialBackend();
-      if (ces.isAvailable()) {
-        _resolvedBackend = ces;
-      } else {
-        log.warn(
-          "CES_CREDENTIAL_URL is set but CES backend is not available — " +
-            "falling back to local credential store",
-        );
-      }
+async function resolveBackendAsync(): Promise<CredentialBackend> {
+  if (_resolvedBackend) return _resolvedBackend;
+  if (!_resolvePromise) {
+    _resolvePromise = doResolveBackend();
+  }
+  return _resolvePromise;
+}
+
+async function doResolveBackend(): Promise<CredentialBackend> {
+  // 1. CES RPC — primary credential backend for all local modes
+  if (_cesClient) {
+    const cesRpc = new CesRpcCredentialBackend(_cesClient);
+    if (cesRpc.isAvailable()) {
+      _resolvedBackend = cesRpc;
+      return cesRpc;
     }
+    log.warn("CES RPC client is set but not ready — falling back to local credential store");
+  }
 
-    if (!_resolvedBackend) {
-      if (
-        process.env.VELLUM_DEV !== "1" &&
-        getKeychainBackend().isAvailable()
-      ) {
-        _resolvedBackend = getKeychainBackend();
-      } else {
-        _resolvedBackend = getEncryptedStoreBackend();
-      }
+  // 2. CES HTTP — containerized / Docker / managed mode
+  if (getIsContainerized() && process.env.CES_CREDENTIAL_URL) {
+    const ces = createCesCredentialBackend();
+    if (ces.isAvailable()) {
+      _resolvedBackend = ces;
+      return ces;
     }
+    log.warn(
+      "CES_CREDENTIAL_URL is set but CES backend is not available — " +
+        "falling back to local credential store",
+    );
   }
+
+  // 3. Encrypted file store — fallback when CES is unavailable
+  _resolvedBackend = getEncryptedStoreBackend();
   return _resolvedBackend;
 }
 
 /**
- * List all account names across both backends (async).
- *
- * In CES mode, only the CES backend is queried — there are no local stores.
+ * List all account names from the resolved backend (async).
  *
- * When the primary backend is the keychain, this merges keys from the keychain
- * and the encrypted store (for legacy keys that haven't been migrated). The
- * result is deduplicated. When the primary backend is already the encrypted
- * store, only that store is queried.
+ * Queries exactly one backend — no cross-store merge.
  */
 export async function listSecureKeysAsync(): Promise<string[]> {
-  const backend = resolveBackend();
-  const primaryKeys = await backend.list();
-
-  // CES mode — the sidecar is the single source of truth, no local merge.
-  if (backend.name === "ces-http") return primaryKeys;
-
-  // If primary backend is NOT the encrypted store, also check
-  // the encrypted store for legacy keys that haven't been migrated.
-  if (backend !== getEncryptedStoreBackend()) {
-    const encKeys = await getEncryptedStoreBackend().list();
-    const merged = new Set([...primaryKeys, ...encKeys]);
-    return Array.from(merged);
-  }
-
-  return primaryKeys;
+  const backend = await resolveBackendAsync();
+  return backend.list();
 }
 
 // ---------------------------------------------------------------------------
-// Async CRUD — single-writer routing
+// Async CRUD — single-backend routing
 // ---------------------------------------------------------------------------
 
 /**
- * Retrieve a secret from secure storage. Reads from the primary backend
- * first. In CES mode, the sidecar is the single source of truth — no
- * local fallback. In local mode, if the primary backend is the keychain,
- * falls back to the encrypted store for legacy keys that haven't been
- * migrated.
+ * Retrieve a secret from secure storage with richer result metadata.
+ *
+ * Returns both the value (if found) and whether the backend was
+ * unreachable. Callers that need to distinguish "not found" from
+ * "backend down" should use this instead of `getSecureKeyAsync`.
+ *
+ * Reads from exactly one backend — no cross-store fallback.
  */
-export async function getSecureKeyAsync(
+export async function getSecureKeyResultAsync(
   account: string,
-): Promise<string | undefined> {
-  const backend = resolveBackend();
+): Promise<SecureKeyResult> {
+  const backend = await resolveBackendAsync();
   const result = await backend.get(account);
-  if (result != null) return result;
-
-  // CES mode — no local fallback.
-  if (backend.name === "ces-http") return undefined;
-
-  // Legacy fallback: if primary backend is NOT the encrypted store,
-  // check the encrypted store for keys that haven't been migrated.
-  if (backend !== getEncryptedStoreBackend()) {
-    return await getEncryptedStoreBackend().get(account);
+  if (result.value != null) {
+    return { value: result.value, unreachable: false };
   }
+  return { value: undefined, unreachable: result.unreachable };
+}
 
-  return undefined;
+/**
+ * Retrieve a secret from secure storage. Convenience wrapper over
+ * `getSecureKeyResultAsync` that returns only the value.
+ */
+export async function getSecureKeyAsync(
+  account: string,
+): Promise<string | undefined> {
+  const result = await getSecureKeyResultAsync(account);
+  return result.value;
 }
 
 /**
@@ -158,7 +163,7 @@ export async function setSecureKeyAsync(
   account: string,
   value: string,
 ): Promise<boolean> {
-  const backend = resolveBackend();
+  const backend = await resolveBackendAsync();
   const ok = await backend.set(account, value);
   if (!ok) {
     log.warn(
@@ -172,38 +177,13 @@ export async function setSecureKeyAsync(
 /**
  * Delete a secret from secure storage.
  *
- * In containerized mode with CES, deletion is routed exclusively through the
- * CES backend — there are no local stores to clean up.
- *
- * In local mode, always attempts deletion on both the keychain backend (if
- * available) and the encrypted store backend, regardless of routing mode.
- * This cleans up legacy data from both stores.
+ * Deletes from exactly one backend — no cross-store cleanup.
  */
 export async function deleteSecureKeyAsync(
   account: string,
 ): Promise<DeleteResult> {
-  const backend = resolveBackend();
-
-  // In CES mode, the sidecar is the only store — no local cleanup needed.
-  if (backend.name === "ces-http") {
-    return backend.delete(account);
-  }
-
-  const keychain = getKeychainBackend();
-  const enc = getEncryptedStoreBackend();
-
-  let keychainResult: DeleteResult = "not-found";
-  if (keychain.isAvailable()) {
-    keychainResult = await keychain.delete(account);
-  }
-
-  const encResult = await enc.delete(account);
-
-  // Return "error" if either errored
-  if (keychainResult === "error" || encResult === "error") return "error";
-  // Return "deleted" if either deleted
-  if (keychainResult === "deleted" || encResult === "deleted") return "deleted";
-  return "not-found";
+  const backend = await resolveBackendAsync();
+  return backend.delete(account);
 }
 
 // ---------------------------------------------------------------------------
@@ -263,7 +243,8 @@ export async function getMaskedProviderKey(
 
 /** @internal Test-only: reset the cached backends so they're re-created. */
 export function _resetBackend(): void {
-  _keychain = undefined;
+  _cesClient = undefined;
   _encryptedStore = undefined;
   _resolvedBackend = undefined;
+  _resolvePromise = undefined;
 }

package/src/skills/catalog-install.ts

@@ -88,11 +88,7 @@ function getConfigPlatformUrl(): string | undefined {
 }
 
 function getPlatformUrl(): string {
-  return (
-    process.env.VELLUM_PLATFORM_URL ??
-    getConfigPlatformUrl() ??
-    "https://platform.vellum.ai"
-  );
+  return process.env.VELLUM_PLATFORM_URL ?? getConfigPlatformUrl() ?? "";
 }
 
 function buildHeaders(): Record<string, string> {
@@ -107,7 +103,11 @@ function buildHeaders(): Record<string, string> {
 // ─── Catalog operations ──────────────────────────────────────────────────────
 
 export async function fetchCatalog(): Promise<CatalogSkill[]> {
-  const url = `${getPlatformUrl()}/v1/skills/`;
+  const platformUrl = getPlatformUrl();
+  if (!platformUrl) {
+    return [];
+  }
+  const url = `${platformUrl}/v1/skills/`;
   const response = await fetch(url, {
     headers: buildHeaders(),
     signal: AbortSignal.timeout(10000),
@@ -214,7 +214,13 @@ export async function fetchAndExtractSkill(
   skillId: string,
   destDir: string,
 ): Promise<void> {
-  const url = `${getPlatformUrl()}/v1/skills/${encodeURIComponent(skillId)}/`;
+  const platformUrl = getPlatformUrl();
+  if (!platformUrl) {
+    throw new Error(
+      `Cannot fetch skill "${skillId}": VELLUM_PLATFORM_URL is not configured.`,
+    );
+  }
+  const url = `${platformUrl}/v1/skills/${encodeURIComponent(skillId)}/`;
   const response = await fetch(url, {
     headers: buildHeaders(),
     signal: AbortSignal.timeout(15000),

package/src/telemetry/usage-telemetry-reporter.ts

@@ -140,7 +140,7 @@ export class UsageTelemetryReporter {
 
       // Resolve auth context — skip flush when neither auth mode is viable
       const client = await VellumPlatformClient.create();
-      if (!client && !getTelemetryAppToken()) {
+      if (!client && (!getTelemetryAppToken() || !getTelemetryPlatformUrl())) {
         return;
       }
 
@@ -203,7 +203,9 @@ export class UsageTelemetryReporter {
       if (client) {
         resp = await client.fetch(TELEMETRY_PATH, fetchInit);
       } else {
-        const url = `${getTelemetryPlatformUrl()}${TELEMETRY_PATH}`;
+        const platformUrl = getTelemetryPlatformUrl();
+        if (!platformUrl) return;
+        const url = `${platformUrl}${TELEMETRY_PATH}`;
         resp = await fetch(url, {
           ...fetchInit,
           headers: {

package/src/tools/calls/call-start.ts

@@ -46,6 +46,7 @@ export async function executeCallStart(
       | "assistant_number"
       | "user_number"
       | undefined,
+    skipDisclosure: input.skip_disclosure === true,
   });
 
   if (!result.ok) {

package/src/tools/executor.ts

@@ -183,10 +183,6 @@ export class ToolExecutor {
         );
         // Buffer so the shell's own timeout fires first and handles cleanup
         toolTimeoutMs = (shellTimeoutSec + 5) * 1000;
-      } else if (name === "claude_code") {
-        // Claude Code spawns a subprocess that manages its own turn limits
-        // (maxTurns). Give it a generous timeout so it isn't killed mid-task.
-        toolTimeoutMs = 10 * 60 * 1000; // 10 minutes
       } else {
         const rawTimeoutSec = getConfig().timeouts.toolExecutionTimeoutSec;
         toolTimeoutMs = safeTimeoutMs(rawTimeoutSec);

package/src/tools/network/script-proxy/session-manager.ts

@@ -61,10 +61,25 @@ const store = new SessionStore();
 /**
  * Host patterns that are allowed by default through the proxy policy engine,
  * regardless of session configuration. Supports exact matches (e.g.
- * `"localhost"`) and wildcard subdomain patterns (e.g. `"*.vellum.ai"`
- * matches `platform.vellum.ai`, `dev-platform.vellum.ai`, etc.).
+ * `"localhost"`) and wildcard subdomain patterns (e.g. `"*.example.com"`
+ * matches `api.example.com`, `dev.example.com`, etc.).
+ *
+ * Additional patterns can be added via the `PROXY_ALLOWED_HOSTS` env var
+ * (comma-separated, e.g. `"*.example.com,api.foo.bar"`).
  */
-const ALLOWED_HOST_PATTERNS: readonly string[] = ["*.vellum.ai", "localhost"];
+const ALLOWED_HOST_PATTERNS: readonly string[] = (() => {
+  const extra = process.env.PROXY_ALLOWED_HOSTS?.trim();
+  const defaults = ["localhost"];
+  if (extra) {
+    defaults.push(
+      ...extra
+        .split(",")
+        .map((h) => h.trim())
+        .filter(Boolean),
+    );
+  }
+  return defaults;
+})();
 
 /**
  * Returns `true` when `hostname` matches any entry in
@@ -73,7 +88,7 @@ const ALLOWED_HOST_PATTERNS: readonly string[] = ["*.vellum.ai", "localhost"];
 function isAllowedHost(hostname: string): boolean {
   for (const pattern of ALLOWED_HOST_PATTERNS) {
     if (pattern.startsWith("*.")) {
-      const suffix = pattern.slice(1); // e.g. ".vellum.ai"
+      const suffix = pattern.slice(1); // e.g. ".example.com"
       if (hostname.endsWith(suffix) || hostname === pattern.slice(2)) {
         return true;
       }

package/src/tools/network/web-fetch.ts

@@ -573,7 +573,9 @@ export async function executeWebFetch(
       Accept:
         "text/markdown, text/html;q=0.9, application/xhtml+xml;q=0.9, text/plain;q=0.8, application/json;q=0.7, */*;q=0.6",
       "Accept-Encoding": "identity",
-      "User-Agent": "VellumAssistant/1.0 (+https://vellum.ai)",
+      "User-Agent":
+        process.env.HTTP_USER_AGENT ||
+        "VellumAssistant/1.0 (+https://vellum.ai)",
     };
 
     let currentUrl = new URL(requestedUrl);

package/src/tools/skills/execute.ts

@@ -30,7 +30,7 @@ export class SkillExecuteTool implements Tool {
           activity: {
             type: "string",
             description:
-              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",
+              "Brief non-technical explanation of what you are doing and why, shown to the user as a progress update.",
           },
         },
         required: ["tool", "input", "activity"],

package/src/tools/types.ts

@@ -118,14 +118,6 @@ export interface ToolContext {
   proxyToolResolver?: ProxyToolResolver;
   /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
   allowedToolNames?: Set<string>;
-  /** Request user confirmation for a sub-tool operation (used by claude_code tool). */
-  requestConfirmation?: (req: {
-    toolName: string;
-    input: Record<string, unknown>;
-    riskLevel: string;
-    executionTarget?: ExecutionTarget;
-    principal?: string;
-  }) => Promise<{ decision: "allow" | "deny" }>;
   /** Prompt the user for a secret value via native SecureField UI. */
   requestSecret?: (params: {
     service: string;

package/src/util/errors.ts

@@ -20,9 +20,6 @@ export enum ErrorCode {
   // WASM integrity check failures
   INTEGRITY_ERROR = "INTEGRITY_ERROR",
 
-  // Secret detected in inbound content
-  INGRESS_BLOCKED = "INGRESS_BLOCKED",
-
   // Internal/unexpected errors
   INTERNAL_ERROR = "INTERNAL_ERROR",
 }
@@ -178,12 +175,3 @@ export class IntegrityError extends AssistantError {
   }
 }
 
-export class IngressBlockedError extends AssistantError {
-  constructor(
-    message: string,
-    public readonly detectedTypes: string[],
-  ) {
-    super(message, ErrorCode.INGRESS_BLOCKED);
-    this.name = "IngressBlockedError";
-  }
-}

package/src/util/platform.ts

@@ -3,7 +3,6 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
-  writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -45,25 +44,6 @@ export function getClipboardCommand(): string | null {
   return null;
 }
 
-/**
- * Read and parse the lockfile (~/.vellum.lock.json).
- * Respects BASE_DATA_DIR for non-standard home directories.
- * Returns null if the file doesn't exist or is malformed.
- */
-export function readLockfile(): Record<string, unknown> | null {
-  const base = getBaseDataDir() || homedir();
-  const lockPath = join(base, ".vellum.lock.json");
-  if (!existsSync(lockPath)) return null;
-  try {
-    const raw = JSON.parse(readFileSync(lockPath, "utf-8"));
-    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
-      return raw as Record<string, unknown>;
-    }
-  } catch {
-    // malformed JSON
-  }
-  return null;
-}
 
 /**
  * Resolve the instance data directory from the lockfile.
@@ -155,45 +135,18 @@ export function resolveInstanceDataDir(): string | undefined {
  * (see migration 007-assistant-id-to-self). However, the desktop UI
  * sends the real assistant ID (e.g., "vellum-true-eel") while the
  * inbound call path resolves phone numbers to config keys (typically
- * "self"). This function maps any known lockfile assistant ID to "self"
+ * "self"). This function maps the current assistant's ID to "self"
  * so both sides use a consistent DB key.
- *
- * Multi-instance safety: each daemon process runs with a scoped
- * BASE_DATA_DIR, so readLockfile() only sees the lockfile for this
- * instance. The mapping to "self" is correct because each daemon is
- * single-tenant — it only manages its own instance's data.
  */
 export function normalizeAssistantId(assistantId: string): string {
   if (assistantId === "self") return "self";
 
-  try {
-    const lockData = readLockfile();
-    const assistants = lockData?.assistants as
-      | Array<Record<string, unknown>>
-      | undefined;
-    if (assistants) {
-      for (const entry of assistants) {
-        if (entry.assistantId === assistantId) return "self";
-      }
-    }
-  } catch {
-    // lockfile unreadable — return as-is
-  }
+  const ownName = process.env.VELLUM_ASSISTANT_NAME;
+  if (ownName && assistantId === ownName) return "self";
 
   return assistantId;
 }
 
-/**
- * Write data to the primary lockfile (~/.vellum.lock.json).
- * Respects BASE_DATA_DIR for non-standard home directories.
- */
-export function writeLockfile(data: Record<string, unknown>): void {
-  const base = getBaseDataDir() || homedir();
-  writeFileSync(
-    join(base, ".vellum.lock.json"),
-    JSON.stringify(data, null, 2) + "\n",
-  );
-}
 
 /**
  * Returns the root ~/.vellum directory. User-facing files (config, prompt

package/src/workspace/git-service.ts

@@ -753,8 +753,11 @@ export class WorkspaceGitService {
    * Must be called with the mutex lock held.
    */
   private async ensureCommitIdentityLocked(): Promise<void> {
-    await this.execGit(["config", "user.name", "Vellum Assistant"]);
-    await this.execGit(["config", "user.email", "assistant@vellum.ai"]);
+    const gitName = process.env.ASSISTANT_GIT_USER_NAME || "Vellum Assistant";
+    const gitEmail =
+      process.env.ASSISTANT_GIT_USER_EMAIL || "assistant@vellum.ai";
+    await this.execGit(["config", "user.name", gitName]);
+    await this.execGit(["config", "user.email", gitEmail]);
   }
 
   /**

package/src/workspace/migrations/001-avatar-rename.ts

@@ -22,4 +22,19 @@ export const avatarRenameMigration: WorkspaceMigration = {
       renameSync(oldTraits, newTraits);
     }
   },
+  down(workspaceDir: string): void {
+    const avatarDir = join(workspaceDir, "data", "avatar");
+
+    const newImage = join(avatarDir, "avatar-image.png");
+    const oldImage = join(avatarDir, "custom-avatar.png");
+    if (existsSync(newImage) && !existsSync(oldImage)) {
+      renameSync(newImage, oldImage);
+    }
+
+    const newTraits = join(avatarDir, "character-traits.json");
+    const oldTraits = join(avatarDir, "avatar-components.json");
+    if (existsSync(newTraits) && !existsSync(oldTraits)) {
+      renameSync(newTraits, oldTraits);
+    }
+  },
 };

package/src/workspace/migrations/003-seed-device-id.ts

@@ -1,4 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
 import { getDeviceIdBaseDir } from "../../util/device-id.js";
@@ -97,4 +103,14 @@ export const seedDeviceIdMigration: WorkspaceMigration = {
       // Best-effort — getDeviceId() will generate a new one if this fails.
     }
   },
+  down(_workspaceDir: string): void {
+    // The forward migration seeds deviceId in ~/.vellum/device.json from the
+    // lockfile. Reverse by removing device.json entirely — getDeviceId() will
+    // generate a fresh one on next startup if needed.
+    const base = getDeviceIdBaseDir();
+    const devicePath = join(base, ".vellum", "device.json");
+    if (existsSync(devicePath)) {
+      unlinkSync(devicePath);
+    }
+  },
 };