@vellumai/assistant 0.5.0 → 0.5.2

package/src/tools/AGENTS.md

@@ -1,18 +1,14 @@
 # Tools - Agent Instructions
 
-## No New Tools Policy
+## New Non-Skill Tools Are Strongly Discouraged
 
-**New tool registrations require approval from Team Jarvis.**
+**Prefer skills over new non-skill tool registrations.** Non-skill tools require approval from Team Jarvis.
 
-The tool registration system (`class ... implements Tool` + `registerTool()`) is being phased out in favor of skill-based approaches. Before adding a new tool, contact Team Jarvis for approval.
+Skills are the preferred approach for adding new capabilities — they are progressively disclosed into context, more portable, and can be iterated on independently. New non-skill tool registrations (`class ... implements Tool` + `registerTool()`) carry additional costs:
 
-## Why This Policy Exists
+1. **Context overhead** — Each registered tool adds to the system prompt and increases token usage for every conversation.
 
-1. **Skills are preferred** - The project direction is to teach the assistant CLI tools via skills rather than hardcoding tool implementations. Skills are progressively disclosed into context, are more portable, and are often self-contained.
-
-2. **Context overhead** - Each registered tool adds to the system prompt and increases token usage for every conversation.
-
-3. **Maintenance burden** - Tools require ongoing maintenance, testing, and security review. Skills can be iterated on independently.
+2. **Maintenance burden** — Tools require ongoing maintenance, testing, and security review.
 
 ## What To Do Instead
 
@@ -26,7 +22,7 @@ Instead of creating a new tool, consider:
 
 ## Approved Exception: Credential Execution Service (CES) Tools
 
-The following three CES tools are the only approved exception to the no-new-tools policy:
+The following three CES tools are approved exceptions that justify tool registrations over skills:
 
 | Tool                         | Purpose                                                                                                                                                    |
 | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/src/tools/apps/executors.ts

@@ -10,11 +10,8 @@
 
 import { compileApp } from "../../bundler/app-compiler.js";
 import { generateAppIcon } from "../../media/app-icon-generator.js";
-import type {
-  AppDefinition,
-  EditEngineResult,
-} from "../../memory/app-store.js";
-import { getAppsDir, isMultifileApp } from "../../memory/app-store.js";
+import type { AppDefinition } from "../../memory/app-store.js";
+import { getAppDirPath } from "../../memory/app-store.js";
 
 // ---------------------------------------------------------------------------
 // Shared result type
@@ -35,9 +32,6 @@ export interface ExecutorResult {
 export interface AppStoreReader {
   getApp(id: string): AppDefinition | null;
   listApps(): AppDefinition[];
-  queryAppRecords(appId: string): unknown[];
-  listAppFiles(appId: string): string[];
-  readAppFile(appId: string, path: string): string;
 }
 
 export interface AppStoreWriter {
@@ -61,13 +55,6 @@ export interface AppStoreWriter {
   ): AppDefinition;
   deleteApp(id: string): void;
   writeAppFile(appId: string, path: string, content: string): void;
-  editAppFile(
-    appId: string,
-    path: string,
-    oldString: string,
-    newString: string,
-    replaceAll?: boolean,
-  ): EditEngineResult;
 }
 
 export type AppStore = AppStoreReader & AppStoreWriter;
@@ -81,28 +68,6 @@ export type ProxyResolver = (
   input: Record<string, unknown>,
 ) => Promise<ExecutorResult>;
 
-// ---------------------------------------------------------------------------
-// Path resolution - multifile apps default to src/ for file operations
-// ---------------------------------------------------------------------------
-
-/**
- * For multifile (formatVersion 2) apps, prepend `src/` to paths that don't
- * already target a known top-level directory (src/, dist/, records/).
- * Legacy apps pass through unchanged.
- */
-export function resolveAppFilePath(app: AppDefinition, path: string): string {
-  if (!isMultifileApp(app)) return path;
-  const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
-  if (
-    normalized.startsWith("src/") ||
-    normalized.startsWith("dist/") ||
-    normalized.startsWith("records/")
-  ) {
-    return normalized;
-  }
-  return `src/${normalized}`;
-}
-
 // ---------------------------------------------------------------------------
 // app_create
 // ---------------------------------------------------------------------------
@@ -222,8 +187,7 @@ render(<App />, document.getElementById('app')!);
     store.writeAppFile(app.id, "src/main.tsx", mainTsx);
 
     // Compile src/ → dist/
-    const { join } = await import("node:path");
-    const appDir = join(getAppsDir(), app.id);
+    const appDir = getAppDirPath(app.id);
     const compileResult = await compileApp(appDir);
     if (!compileResult.ok) {
       return {
@@ -286,72 +250,6 @@ render(<App />, document.getElementById('app')!);
   return { content: JSON.stringify(app), isError: false };
 }
 
-// ---------------------------------------------------------------------------
-// app_list
-// ---------------------------------------------------------------------------
-
-export function executeAppList(store: AppStoreReader): ExecutorResult {
-  const apps = store.listApps().map((a) => ({
-    id: a.id,
-    name: a.name,
-    description: a.description,
-    updatedAt: a.updatedAt,
-  }));
-  return { content: JSON.stringify(apps), isError: false };
-}
-
-// ---------------------------------------------------------------------------
-// app_query
-// ---------------------------------------------------------------------------
-
-export interface AppQueryInput {
-  app_id: string;
-}
-
-export function executeAppQuery(
-  input: AppQueryInput,
-  store: AppStoreReader,
-): ExecutorResult {
-  const records = store.queryAppRecords(input.app_id);
-  return { content: JSON.stringify(records), isError: false };
-}
-
-// ---------------------------------------------------------------------------
-// app_update
-// ---------------------------------------------------------------------------
-
-export interface AppUpdateInput {
-  app_id: string;
-  name?: string;
-  description?: string;
-  schema_json?: string;
-  html?: string;
-  pages?: Record<string, string>;
-}
-
-export function executeAppUpdate(
-  input: AppUpdateInput,
-  store: AppStore,
-): ExecutorResult {
-  const updates: Partial<
-    Pick<
-      AppDefinition,
-      "name" | "description" | "schemaJson" | "htmlDefinition" | "pages"
-    >
-  > = {};
-  if (typeof input.name === "string") updates.name = input.name;
-  if (typeof input.description === "string")
-    updates.description = input.description;
-  if (typeof input.schema_json === "string")
-    updates.schemaJson = input.schema_json;
-  if (typeof input.html === "string") updates.htmlDefinition = input.html;
-  if (input.pages && typeof input.pages === "object")
-    updates.pages = input.pages;
-
-  const app = store.updateApp(input.app_id, updates);
-  return { content: JSON.stringify(app), isError: false };
-}
-
 // ---------------------------------------------------------------------------
 // app_delete
 // ---------------------------------------------------------------------------
@@ -372,131 +270,15 @@ export function executeAppDelete(
 }
 
 // ---------------------------------------------------------------------------
-// app_file_list
-// ---------------------------------------------------------------------------
-
-export interface AppFileListInput {
-  app_id: string;
-}
-
-export function executeAppFileList(
-  input: AppFileListInput,
-  store: AppStoreReader,
-): ExecutorResult {
-  const files = store.listAppFiles(input.app_id);
-  const app = store.getApp(input.app_id);
-
-  if (app && isMultifileApp(app)) {
-    // Separate build output paths from source paths without mutating the
-    // file path strings - consumers need clean paths for subsequent tool calls.
-    const buildOutputPaths = files.filter((f) =>
-      f.replace(/\\/g, "/").startsWith("dist/"),
-    );
-    return {
-      content: JSON.stringify({
-        files,
-        buildOutput: buildOutputPaths,
-      }),
-      isError: false,
-    };
-  }
-
-  return { content: JSON.stringify(files), isError: false };
-}
-
-// ---------------------------------------------------------------------------
-// app_file_read
-// ---------------------------------------------------------------------------
-
-export interface AppFileReadInput {
-  app_id: string;
-  path: string;
-  offset?: number;
-  limit?: number;
-}
-
-export function executeAppFileRead(
-  input: AppFileReadInput,
-  store: AppStoreReader,
-): ExecutorResult {
-  const offset = input.offset ?? 1;
-  const limit = input.limit;
-
-  const app = store.getApp(input.app_id);
-  const resolvedPath = app ? resolveAppFilePath(app, input.path) : input.path;
-  const raw = store.readAppFile(input.app_id, resolvedPath);
-  const allLines = raw.split("\n");
-  const startIndex = Math.max(0, offset - 1);
-  const sliced =
-    limit != null
-      ? allLines.slice(startIndex, startIndex + limit)
-      : allLines.slice(startIndex);
-
-  const formatted = sliced
-    .map((line, i) => {
-      const lineNum = startIndex + i + 1;
-      return `${String(lineNum).padStart(6)}\t${line}`;
-    })
-    .join("\n");
-
-  return { content: formatted, isError: false };
-}
-
-// ---------------------------------------------------------------------------
-// app_file_edit
-// ---------------------------------------------------------------------------
-
-export interface AppFileEditInput {
-  app_id: string;
-  path: string;
-  old_string: string;
-  new_string: string;
-  replace_all?: boolean;
-  status?: string;
-}
-
-export function executeAppFileEdit(
-  input: AppFileEditInput,
-  store: AppStore,
-): ExecutorResult {
-  if (!input.old_string) {
-    return {
-      content: JSON.stringify({ error: "old_string must not be empty" }),
-      isError: true,
-    };
-  }
-
-  const app = store.getApp(input.app_id);
-  const resolvedPath = app ? resolveAppFilePath(app, input.path) : input.path;
-
-  const replaceAll = input.replace_all ?? false;
-  const result = store.editAppFile(
-    input.app_id,
-    resolvedPath,
-    input.old_string,
-    input.new_string,
-    replaceAll,
-  );
-  return {
-    content: JSON.stringify(result),
-    isError: false,
-    status: input.status,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// app_file_write
+// app_refresh
 // ---------------------------------------------------------------------------
 
-export interface AppFileWriteInput {
+export interface AppRefreshInput {
   app_id: string;
-  path: string;
-  content: string;
-  status?: string;
 }
 
-export function executeAppFileWrite(
-  input: AppFileWriteInput,
+export function executeAppRefresh(
+  input: AppRefreshInput,
   store: AppStore,
 ): ExecutorResult {
   const app = store.getApp(input.app_id);
@@ -507,12 +289,16 @@ export function executeAppFileWrite(
     };
   }
 
-  const resolvedPath = resolveAppFilePath(app, input.path);
-  store.writeAppFile(input.app_id, resolvedPath, input.content);
+  // Empty update bumps updatedAt timestamp, triggering recompilation and
+  // surface refresh on the client side.
+  const updated = store.updateApp(input.app_id, {});
   return {
-    content: JSON.stringify({ written: true, path: resolvedPath }),
+    content: JSON.stringify({
+      refreshed: true,
+      appId: updated.id,
+      name: updated.name,
+    }),
     isError: false,
-    status: input.status,
   };
 }
 
@@ -541,9 +327,8 @@ export async function executeAppGenerateIcon(
   // destroying an existing icon if generation fails.
   const { existsSync, renameSync, unlinkSync } = await import("node:fs");
   const { join } = await import("node:path");
-  const { getAppsDir } = await import("../../memory/app-store.js");
-  const iconPath = join(getAppsDir(), input.app_id, "icon.png");
-  const tempPath = join(getAppsDir(), input.app_id, "icon.tmp.png");
+  const iconPath = join(getAppDirPath(input.app_id), "icon.png");
+  const tempPath = join(getAppDirPath(input.app_id), "icon.tmp.png");
 
   // Temporarily move existing icon aside so generateAppIcon doesn't skip
   if (existsSync(iconPath)) {

package/src/tools/claude-code/claude-code.ts

@@ -4,7 +4,7 @@ import {
 } from "../../commands/cc-command-registry.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
-import { getSecureKeyAsync } from "../../security/secure-keys.js";
+import { getProviderKeyAsync } from "../../security/secure-keys.js";
 import type { WorkerProfile } from "../../swarm/worker-backend.js";
 import { getProfilePolicy } from "../../swarm/worker-backend.js";
 import { getLogger } from "../../util/logger.js";
@@ -203,8 +203,7 @@ export const claudeCodeTool: Tool = {
     const profilePolicy = getProfilePolicy(profileName);
 
     // Validate API key
-    const apiKey =
-      (await getSecureKeyAsync("anthropic")) ?? process.env.ANTHROPIC_API_KEY;
+    const apiKey = await getProviderKeyAsync("anthropic");
     if (!apiKey) {
       return {
         content:

package/src/tools/credentials/vault.ts

@@ -7,8 +7,8 @@ import { orchestrateOAuthConnect } from "../../oauth/connect-orchestrator.js";
 import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
 import {
   disconnectOAuthProvider,
+  getActiveConnection,
   getAppByProviderAndClientId,
-  getConnectionByProviderAndAccount,
   getMostRecentAppByProvider,
   getProvider,
 } from "../../oauth/oauth-store.js";
@@ -66,9 +66,7 @@ async function storeSlackChannelCredential(
     : setSlackChannelConfig(undefined, value);
 }
 
-function formatSlackChannelStatus(
-  result: SlackChannelConfigResult,
-): string {
+function formatSlackChannelStatus(result: SlackChannelConfigResult): string {
   if (result.connected) {
     const teamLabel = result.teamName ?? "Slack";
     const botLabel = result.botUsername ? ` (@${result.botUsername})` : "";
@@ -366,8 +364,7 @@ class CredentialStoreTool implements Tool {
           if (!slackChannelResult.success) {
             return {
               content: `Error: ${
-                slackChannelResult.error ??
-                "failed to configure Slack channel"
+                slackChannelResult.error ?? "failed to configure Slack channel"
               }`,
               isError: true,
             };
@@ -523,10 +520,9 @@ class CredentialStoreTool implements Tool {
           const accountHint = input.account as string | undefined;
           let oauthResult: "disconnected" | "not-found" | "error";
           if (accountHint) {
-            const targetConn = getConnectionByProviderAndAccount(
-              service,
-              accountHint,
-            );
+            const targetConn = getActiveConnection(service, {
+              account: accountHint,
+            });
             oauthResult = targetConn
               ? await disconnectOAuthProvider(service, undefined, targetConn.id)
               : "not-found";
@@ -778,8 +774,7 @@ class CredentialStoreTool implements Tool {
           if (!slackChannelResult.success) {
             return {
               content: `Error: ${
-                slackChannelResult.error ??
-                "failed to configure Slack channel"
+                slackChannelResult.error ?? "failed to configure Slack channel"
               }`,
               isError: true,
             };

package/src/tools/host-filesystem/read.ts

@@ -54,6 +54,19 @@ class HostFileReadTool implements Tool {
       };
     }
 
+    // Image files must be handled locally — the host-file proxy protocol
+    // only carries {content, isError} and cannot transport contentBlocks
+    // (base64 image data). Check for image extensions before the proxy
+    // short-circuit so image reads work in managed/macOS+iOS sessions.
+    const ext = extname(rawPath).toLowerCase();
+    if (IMAGE_EXTENSIONS.has(ext)) {
+      const pathCheck = hostPolicy(rawPath);
+      if (!pathCheck.ok) {
+        return { content: `Error: ${pathCheck.error}`, isError: true };
+      }
+      return readImageFile(pathCheck.resolved);
+    }
+
     // Proxy to connected client for execution on the user's machine
     // when a capable client is available (managed/cloud-hosted mode).
     if (context.hostFileProxy?.isAvailable()) {
@@ -69,16 +82,6 @@ class HostFileReadTool implements Tool {
       );
     }
 
-    // For image files, delegate to the shared image reader.
-    const ext = extname(rawPath).toLowerCase();
-    if (IMAGE_EXTENSIONS.has(ext)) {
-      const pathCheck = hostPolicy(rawPath);
-      if (!pathCheck.ok) {
-        return { content: `Error: ${pathCheck.error}`, isError: true };
-      }
-      return readImageFile(pathCheck.resolved);
-    }
-
     const ops = new FileSystemOps(hostPolicy);
 
     const result = ops.readFileSafe({

package/src/tools/network/__tests__/web-search.test.ts

@@ -16,12 +16,14 @@ mock.module("../../registry.js", () => ({
 
 mock.module("../../../config/loader.js", () => ({
   getConfig: () => ({
-    webSearchProvider: mockWebSearchProvider,
+    services: {
+      "web-search": { provider: mockWebSearchProvider },
+    },
   }),
 }));
 
 mock.module("../../../security/secure-keys.js", () => ({
-  getSecureKeyAsync: async (provider: string) => {
+  getProviderKeyAsync: async (provider: string) => {
     if (provider === "brave") return mockBraveSecureKey;
     if (provider === "perplexity") return mockPerplexitySecureKey;
     return undefined;

package/src/tools/schedule/list.ts

@@ -62,15 +62,10 @@ export async function executeScheduleList(
       );
     }
 
-    lines.push(
-      `  Enabled: ${job.enabled}`,
-      `  Message: ${job.message}`,
-    );
+    lines.push(`  Enabled: ${job.enabled}`, `  Message: ${job.message}`);
 
     if (!oneShot) {
-      lines.push(
-        `  Next run: ${formatLocalDate(job.nextRunAt)}`,
-      );
+      lines.push(`  Next run: ${formatLocalDate(job.nextRunAt)}`);
     }
 
     lines.push(

package/src/tools/schema-transforms.ts

@@ -29,7 +29,12 @@ export function injectActivityField(
     }
 
     const properties = schema.properties as Record<string, unknown>;
+
     if (schemaDefinesProperty(schema, "activity")) {
+      // Activity is already defined somewhere in the schema (top-level properties
+      // or composite sub-schemas). Don't modify schemas we don't own — MCP tools
+      // may define activity as intentionally optional or with server-specific
+      // semantics.
       return def;
     }
 

package/src/tools/shared/filesystem/format-diff.ts

@@ -1,22 +1,12 @@
-const MAX_DIFF_LINES = 8;
-
 /**
- * Build a compact inline diff from an old→new string replacement.
- * Lines are prefixed with - / + and truncated if the change is large.
+ * Build an inline diff from an old→new string replacement.
+ * Lines are prefixed with - / +.
  */
 export function formatEditDiff(oldString: string, newString: string): string {
   const removed =
-    oldString.length > 0
-      ? truncateLines(oldString.split("\n"), MAX_DIFF_LINES).map(
-          (l) => `- ${l}`,
-        )
-      : [];
+    oldString.length > 0 ? oldString.split("\n").map((l) => `- ${l}`) : [];
   const added =
-    newString.length > 0
-      ? truncateLines(newString.split("\n"), MAX_DIFF_LINES).map(
-          (l) => `+ ${l}`,
-        )
-      : [];
+    newString.length > 0 ? newString.split("\n").map((l) => `+ ${l}`) : [];
 
   return [...removed, ...added].join("\n");
 }
@@ -36,10 +26,3 @@ export function formatWriteSummary(
   const oldLineCount = oldContent.split("\n").length;
   return `(${oldLineCount} → ${newLineCount} lines)`;
 }
-
-function truncateLines(lines: string[], max: number): string[] {
-  if (lines.length <= max) return lines;
-  const kept = lines.slice(0, max);
-  kept.push(`... (${lines.length - max} more lines)`);
-  return kept;
-}

package/src/tools/skills/execute.ts

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

package/src/tools/tool-manifest.ts

@@ -11,8 +11,6 @@ import {
   isCesSecureInstallEnabled,
   isCesToolsEnabled,
 } from "../credential-execution/feature-gates.js";
-import { assetMaterializeTool } from "./assets/materialize.js";
-import { assetSearchTool } from "./assets/search.js";
 import { makeAuthenticatedRequestTool } from "./credential-execution/make-authenticated-request.js";
 import { manageSecureCommandTool } from "./credential-execution/manage-secure-command-tool.js";
 import { runAuthenticatedCommandTool } from "./credential-execution/run-authenticated-command.js";
@@ -63,8 +61,6 @@ export const eagerModuleToolNames: string[] = [
   "skill_execute",
   "skill_load",
   "request_system_permission",
-  "asset_search",
-  "asset_materialize",
 ];
 
 // ── Explicit tool instances ─────────────────────────────────────────
@@ -85,8 +81,6 @@ export const explicitTools: Tool[] = [
   skillExecuteTool,
   skillLoadTool,
   requestSystemPermissionTool,
-  assetSearchTool,
-  assetMaterializeTool,
   // Always-explicit tools
   memoryManageTool,
   memoryRecallTool,

package/src/tools/ui-surface/definitions.ts

@@ -30,7 +30,7 @@ export const uiShowTool: Tool = {
   description:
     "Show structured data or UI to the user. For long-form writing use the document skill; for interactive apps use the app-builder skill.\n\n" +
     "Surface types (data shapes):\n" +
-    "- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: \"weather_forecast\" (native weather widget), \"task_progress\" (live step tracker - update via ui_update on data.templateData; shape: { title, status: \"in_progress\"|\"completed\"|\"failed\", steps: [{ label, status: \"pending\"|\"in_progress\"|\"completed\"|\"failed\", detail? }] })\n" +
+    '- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: "weather_forecast" (native weather widget), "task_progress" (live step tracker - update via ui_update on data.templateData; shape: { title, status: "in_progress"|"completed"|"failed", steps: [{ label, status: "pending"|"in_progress"|"completed"|"failed", detail? }] })\n' +
     '- table: { columns: [{ id, label, width? }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
     '- form: { description?, fields: [{ id, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label, placeholder?, required?, defaultValue?, options?: [{ label, value }] }], submitLabel? }. Multi-page: { pages: [{ id, title, description?, fields }], pageLabels?: { next?, back?, submit? }, submitLabel? }\n' +
     '- list: { items: [{ id, title, subtitle?, icon?, selected? }], selectionMode: "single"|"multiple"|"none" }\n' +
@@ -91,7 +91,7 @@ export const uiShowTool: Tool = {
             type: "string",
             enum: ["inline", "panel"],
             description:
-              'Where to render the surface. "inline" embeds it in the chat message. "panel" shows a floating window. Defaults to "inline".',
+              'Where to render the surface. "inline" embeds it in the chat message. "panel" shows a floating window. Defaults to "inline". Prefer inline — only use panel when the user explicitly asks for a separate window.',
           },
           await_action: {
             type: "boolean",

package/src/util/device-id.ts

@@ -1,9 +1,16 @@
 /**
  * Device ID resolver.
  *
- * Reads or creates a stable per-device UUID stored in ~/.vellum/device.json.
- * The file is a JSON object (`{ "deviceId": "<uuid>" }`) extensible for
- * future per-device metadata.
+ * Reads or creates a stable per-device UUID stored in device.json under the
+ * Vellum config directory. The file is a JSON object (`{ "deviceId": "<uuid>" }`)
+ * extensible for future per-device metadata.
+ *
+ * Path resolution:
+ *   - Containerized (IS_CONTAINERIZED=true): uses BASE_DATA_DIR, which maps to a
+ *     persistent volume. Each container is effectively its own "device."
+ *   - Local (single or multi-instance): uses homedir() so all instances on the
+ *     same machine share a single device ID, even when BASE_DATA_DIR is set to
+ *     an instance-scoped directory.
  *
  * The value is cached in memory after the first successful read/write.
  * Falls back to a generated UUID if the file cannot be read or written.
@@ -14,18 +21,34 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { getBaseDataDir, getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "./logger.js";
 
 const log = getLogger("device-id");
 
 let cached: string | undefined;
 
+/**
+ * Resolve the base directory for device.json.
+ *
+ * In containerized environments, BASE_DATA_DIR points to a persistent volume
+ * and homedir() is ephemeral, so we must use BASE_DATA_DIR.
+ * In local environments (including multi-instance), homedir() is stable and
+ * shared across instances, giving a true per-machine device ID.
+ */
+export function getDeviceIdBaseDir(): string {
+  if (getIsContainerized()) {
+    return getBaseDataDir() || homedir();
+  }
+  return homedir();
+}
+
 /**
  * Get the stable device ID for this machine.
  *
  * Resolution order:
  *   1. Cached in-memory value (populated on first call)
- *   2. `deviceId` field from ~/.vellum/device.json
+ *   2. `deviceId` field from device.json
  *   3. Generate a new UUID, persist it to device.json, and return it
  *
  * On any read/write error the generated UUID is still cached so the
@@ -36,7 +59,7 @@ export function getDeviceId(): string {
     return cached;
   }
 
-  const vellumDir = join(homedir(), ".vellum");
+  const vellumDir = join(getDeviceIdBaseDir(), ".vellum");
   const filePath = join(vellumDir, "device.json");
   const generated = randomUUID();