@vellumai/assistant 0.7.1 → 0.7.3

package/src/workspace/migrations/022-move-hooks-to-workspace.ts

@@ -1,7 +1,7 @@
 /**
  * Workspace migration 022: Move hooks directory from root to workspace.
  *
- * Previously, `~/.vellum/hooks/` lived directly under getRootDir(). This
+ * Previously, `~/.vellum/hooks/` lived directly under the Vellum root. This
  * migration moves existing hook directories and files into
  * `~/.vellum/workspace/hooks/` so that getWorkspaceHooksDir() resolves
  * correctly under the workspace.
@@ -19,23 +19,17 @@ import {
   renameSync,
   rmSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const moveHooksToWorkspaceMigration: WorkspaceMigration = {
   id: "022-move-hooks-to-workspace",
   description: "Move hooks directory from root to workspace",
 
   run(workspaceDir: string): void {
-    const oldHooksDir = join(getRootDir(), "hooks");
+    const oldHooksDir = join(getVellumRoot(), "hooks");
     const newHooksDir = join(workspaceDir, "hooks");
 
     mkdirSync(newHooksDir, { recursive: true });
@@ -65,7 +59,7 @@ export const moveHooksToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const oldHooksDir = join(getRootDir(), "hooks");
+    const oldHooksDir = join(getVellumRoot(), "hooks");
     const newHooksDir = join(workspaceDir, "hooks");
 
     mkdirSync(oldHooksDir, { recursive: true });

package/src/workspace/migrations/023-move-config-files-to-workspace.ts

@@ -2,23 +2,16 @@
  * Workspace migration 023: Move config/state JSON files from root to workspace.
  *
  * Previously, dictation-profiles.json, email-guardrails.json, and
- * active-call-leases.json lived directly under getRootDir() (~/.vellum/).
+ * active-call-leases.json lived directly under the Vellum root (~/.vellum/).
  * This migration moves them into the workspace directory so they follow
  * the workspace convention for organizational consistency.
  */
 
 import { existsSync, renameSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
-
+import { getVellumRoot } from "./utils.js";
 /** Files to move from root → workspace. */
 const CONFIG_FILES = [
   "dictation-profiles.json",
@@ -32,7 +25,7 @@ export const moveConfigFilesToWorkspaceMigration: WorkspaceMigration = {
     "Move dictation-profiles, email-guardrails, and active-call-leases from root to workspace",
 
   run(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     for (const file of CONFIG_FILES) {
       const oldPath = join(rootDir, file);
@@ -60,7 +53,7 @@ export const moveConfigFilesToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     for (const file of CONFIG_FILES) {
       const newPath = join(workspaceDir, file);

package/src/workspace/migrations/024-move-runtime-files-to-workspace.ts

@@ -25,17 +25,10 @@ import {
   renameSync,
   unlinkSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-/** Inlined from platform.ts to satisfy migration self-containment rule (AGENTS.md). */
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
-
+import { getVellumRoot } from "./utils.js";
 /** Individual files to move from root → workspace (with optional subdirectory). */
 const FILE_MOVES: Array<{ name: string; subdir?: string }> = [
   { name: "daemon-stderr.log", subdir: "logs" },
@@ -93,7 +86,7 @@ export const moveRuntimeFilesToWorkspaceMigration: WorkspaceMigration = {
     "Move daemon-stderr.log, daemon-startup.lock, embed-worker.pid, external/, and bin/ from root to workspace",
 
   run(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     // Move individual files
     for (const { name, subdir } of FILE_MOVES) {
@@ -110,7 +103,7 @@ export const moveRuntimeFilesToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const rootDir = getRootDir();
+    const rootDir = getVellumRoot();
 
     // Move individual files back
     for (const { name, subdir } of FILE_MOVES) {

package/src/workspace/migrations/040-seed-latency-callsite-defaults.ts

@@ -22,8 +22,9 @@ import type { WorkspaceMigration } from "./types.js";
  *   2. **Fresh install** (config.json absent): write a minimal starter
  *      config with just the callSite seeds, using the default provider
  *      (anthropic — same as the schema default). `loadConfig()` runs
- *      after migrations and backfills the remaining schema defaults via
- *      `deepMergeMissing`, which preserves our seeded callSites.
+ *      after migrations and applies schema defaults only to the
+ *      in-memory config (disk is left untouched), so our seeded
+ *      callSites are preserved verbatim.
  *
  * Without the fresh-install branch, new users permanently fall through
  * to `llm.default` (opus + max effort) because `LLMSchema.callSites`

package/src/workspace/migrations/050-seed-main-agent-opus-callsite.ts

@@ -12,7 +12,8 @@ import type { WorkspaceMigration } from "./types.js";
  *      `llm.callSites` without overwriting a user-defined override.
  *   2. **Fresh install** (config.json absent): write a minimal starter
  *      config with just this seed. `loadConfig()` runs after migrations
- *      and backfills the remaining schema defaults via `deepMergeMissing`.
+ *      and applies schema defaults to the in-memory config without
+ *      rewriting disk, so the seeded callSite is preserved as-is.
  *
  * Applied only when:
  *   - the resolved provider is Anthropic (other providers own their

package/src/workspace/migrations/059-move-pid-to-workspace.ts

@@ -7,22 +7,17 @@
  */
 
 import { existsSync, renameSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const movePidToWorkspaceMigration: WorkspaceMigration = {
   id: "059-move-pid-to-workspace",
   description: "Move vellum.pid from root to workspace",
 
   run(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "vellum.pid");
+    const oldPath = join(getVellumRoot(), "vellum.pid");
     const newPath = join(workspaceDir, "vellum.pid");
     if (!existsSync(oldPath)) return;
     if (existsSync(newPath)) {
@@ -37,7 +32,7 @@ export const movePidToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "vellum.pid");
+    const oldPath = join(getVellumRoot(), "vellum.pid");
     const newPath = join(workspaceDir, "vellum.pid");
     if (!existsSync(newPath)) return;
     if (existsSync(oldPath)) {

package/src/workspace/migrations/061-move-backup-key-to-workspace.ts

@@ -11,22 +11,17 @@
  */
 
 import { copyFileSync, existsSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
-
-function getRootDir(): string {
-  const base = process.env.BASE_DATA_DIR?.trim() || homedir();
-  return join(base, ".vellum");
-}
+import { getVellumRoot } from "./utils.js";
 
 export const moveBackupKeyToWorkspaceMigration: WorkspaceMigration = {
   id: "061-move-backup-key-to-workspace",
   description: "Move backup.key from protected/ to workspace",
 
   run(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "protected", "backup.key");
+    const oldPath = join(getVellumRoot(), "protected", "backup.key");
     const newPath = join(workspaceDir, ".backup.key");
     if (!existsSync(oldPath)) return;
     if (existsSync(newPath)) {
@@ -42,7 +37,7 @@ export const moveBackupKeyToWorkspaceMigration: WorkspaceMigration = {
   },
 
   down(workspaceDir: string): void {
-    const oldPath = join(getRootDir(), "protected", "backup.key");
+    const oldPath = join(getVellumRoot(), "protected", "backup.key");
     const newPath = join(workspaceDir, ".backup.key");
     if (!existsSync(newPath)) return;
     if (existsSync(oldPath)) {

package/src/workspace/migrations/065-bump-stale-heartbeat-interval.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+const THIRTY_MINUTES_MS = 30 * 60 * 1000;
+const LEGACY_DEFAULT_INTERVALS_MS = new Set([
+  3 * 60 * 60 * 1000,
+  6 * 60 * 60 * 1000,
+]);
+
+/**
+ * Bump stale baked heartbeat defaults to 30 minutes.
+ *
+ * Older first-launch config files materialized the then-current heartbeat
+ * default into `config.json`, so changing the schema default alone would not
+ * affect existing default users. A workspace could have intentionally selected
+ * one of these exact intervals; product intent is still to move legacy 3h/6h
+ * heartbeat schedules to the 30-minute default, and those users can reset the
+ * interval after upgrade.
+ */
+export const bumpStaleHeartbeatIntervalMigration: WorkspaceMigration = {
+  id: "065-bump-stale-heartbeat-interval",
+  description:
+    "Bump legacy heartbeat.intervalMs defaults of 3h/6h to the current 30-minute default",
+  run(workspaceDir: string): void {
+    const configPath = join(workspaceDir, "config.json");
+    if (!existsSync(configPath)) return;
+
+    let config: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+      config = raw as Record<string, unknown>;
+    } catch {
+      return;
+    }
+
+    const heartbeat = config.heartbeat;
+    if (!heartbeat || typeof heartbeat !== "object" || Array.isArray(heartbeat))
+      return;
+
+    const heartbeatConfig = heartbeat as Record<string, unknown>;
+    const intervalMs = heartbeatConfig.intervalMs;
+    if (
+      typeof intervalMs !== "number" ||
+      !LEGACY_DEFAULT_INTERVALS_MS.has(intervalMs)
+    ) {
+      return;
+    }
+
+    heartbeatConfig.intervalMs = THIRTY_MINUTES_MS;
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  },
+  down(_workspaceDir: string): void {
+    // Forward-only: the stale value may have been a schema-default artifact,
+    // while 30 minutes may also have been explicitly configured later. Without
+    // per-workspace state we cannot safely distinguish those cases.
+  },
+};

package/src/workspace/migrations/066-seed-heartbeat-callsite-cost-default.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * Seed a cheap, bounded default for the `heartbeatAgent` LLM call site.
+ *
+ * Heartbeats are default-on and now run frequently, so they should not inherit
+ * the workspace's active chat profile. The default managed profile is Sonnet
+ * with high effort and thinking enabled, which is appropriate for interactive
+ * chat but too expensive for a periodic background triage pass.
+ *
+ * Preserve user-owned model selection. If `heartbeatAgent` already has a
+ * `profile`, `provider`, or `model`, this migration leaves the entry unchanged
+ * so call-site leaves do not silently override the selected profile/model.
+ * Speed-only legacy entries from migration 038 are treated as defaultable.
+ */
+export const seedHeartbeatCallsiteCostDefaultMigration: WorkspaceMigration = {
+  id: "066-seed-heartbeat-callsite-cost-default",
+  description:
+    "Seed cost-optimized defaults for the heartbeatAgent LLM call site",
+  run(workspaceDir: string): void {
+    if (process.env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH) return;
+
+    const configPath = join(workspaceDir, "config.json");
+    const configExisted = existsSync(configPath);
+
+    let config: Record<string, unknown> = {};
+    if (configExisted) {
+      try {
+        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+        config = raw as Record<string, unknown>;
+      } catch {
+        return;
+      }
+    }
+
+    const llm = readObject(config.llm) ?? {};
+    const defaultBlock = readObject(llm.default);
+    const provider = readString(defaultBlock?.provider) ?? "anthropic";
+    const cheapModel = resolveCheapModel(provider);
+    if (cheapModel === undefined) return;
+
+    const callSites = readObject(llm.callSites) ?? {};
+    const existing = readObject(callSites.heartbeatAgent) ?? {};
+    if (hasExplicitModelSelection(existing)) return;
+
+    const seeded: Record<string, unknown> = { ...existing };
+    let changed = false;
+
+    const profiles = readObject(llm.profiles) ?? {};
+    const costProfile = readObject(profiles["cost-optimized"]);
+    if (readString(costProfile?.provider) === provider) {
+      seeded.profile = "cost-optimized";
+    } else {
+      seeded.provider = provider;
+      seeded.model = cheapModel;
+    }
+    changed = true;
+
+    changed = seedMissingLeaf(seeded, "maxTokens", 2048) || changed;
+    changed = seedMissingLeaf(seeded, "effort", "low") || changed;
+    changed = seedMissingLeaf(seeded, "temperature", 0) || changed;
+
+    const thinking = readObject(seeded.thinking) ?? {};
+    const seededThinking = { ...thinking };
+    const enabledChanged = seedMissingLeaf(seededThinking, "enabled", false);
+    const streamThinkingChanged = seedMissingLeaf(
+      seededThinking,
+      "streamThinking",
+      false,
+    );
+    const thinkingChanged = enabledChanged || streamThinkingChanged;
+    if (thinkingChanged || readObject(seeded.thinking) === null) {
+      seeded.thinking = seededThinking;
+      changed = true;
+    }
+
+    const contextWindow = readObject(seeded.contextWindow) ?? {};
+    const seededContextWindow = { ...contextWindow };
+    const contextChanged = seedMissingLeaf(
+      seededContextWindow,
+      "maxInputTokens",
+      16_000,
+    );
+    if (contextChanged || readObject(seeded.contextWindow) === null) {
+      seeded.contextWindow = seededContextWindow;
+      changed = true;
+    }
+
+    if (!changed) return;
+
+    callSites.heartbeatAgent = seeded;
+    llm.callSites = callSites;
+    config.llm = llm;
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  },
+  down(_workspaceDir: string): void {
+    // Forward-only: removing the seeded default would make frequent
+    // heartbeats inherit the user's potentially expensive chat profile again.
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers — self-contained per workspace migrations AGENTS.md
+// ---------------------------------------------------------------------------
+
+const CHEAP_MODELS_BY_PROVIDER: Record<string, string> = {
+  anthropic: "claude-haiku-4-5-20251001",
+  openai: "gpt-5.4-nano",
+  gemini: "gemini-3-flash",
+  ollama: "llama3.2",
+  fireworks: "accounts/fireworks/models/kimi-k2p5",
+  openrouter: "anthropic/claude-haiku-4.5",
+};
+
+function resolveCheapModel(provider: string): string | undefined {
+  return CHEAP_MODELS_BY_PROVIDER[provider];
+}
+
+function hasExplicitModelSelection(value: Record<string, unknown>): boolean {
+  return "profile" in value || "provider" in value || "model" in value;
+}
+
+function seedMissingLeaf(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): boolean {
+  if (key in target) return false;
+  target[key] = value;
+  return true;
+}
+
+function readObject(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/workspace/migrations/067-release-notes-safe-storage-limits.ts

@@ -0,0 +1,72 @@
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import type { WorkspaceMigration } from "./types.js";
+
+const log = getLogger(
+  "workspace-migration-067-release-notes-safe-storage-limits",
+);
+
+const MIGRATION_ID = "067-release-notes-safe-storage-limits";
+const MARKER = `<!-- release-note-id:${MIGRATION_ID} -->`;
+
+const RELEASE_NOTE = `${MARKER}
+## Safe storage limits
+
+A new storage protection mode is available behind the safe-storage-limits
+rollout flag. When enabled, the assistant watches workspace disk usage and
+enters cleanup mode if the volume reaches the critical 95% threshold.
+
+In cleanup mode, background processes pause and remote messages, including
+trusted-contact messages, are blocked until the guardian frees enough space or
+explicitly overrides the lock. The macOS app now shows a storage cleanup banner
+that must be acknowledged before cleanup chat continues, then keeps a status
+banner visible while cleanup mode is active.
+`;
+
+export const releaseNotesSafeStorageLimitsMigration: WorkspaceMigration = {
+  id: MIGRATION_ID,
+  description: "Append release notes for safe storage limits to UPDATES.md",
+
+  run(workspaceDir: string): void {
+    const updatesPath = join(workspaceDir, "UPDATES.md");
+
+    try {
+      if (existsSync(updatesPath)) {
+        const existing = readFileSync(updatesPath, "utf-8");
+        if (existing.includes(MARKER)) {
+          return;
+        }
+        const needsLeadingNewline = !existing.endsWith("\n\n");
+        const prefix = existing.endsWith("\n") ? "\n" : "\n\n";
+        appendFileSync(
+          updatesPath,
+          needsLeadingNewline ? `${prefix}${RELEASE_NOTE}` : RELEASE_NOTE,
+          "utf-8",
+        );
+      } else {
+        writeFileSync(updatesPath, RELEASE_NOTE, "utf-8");
+      }
+      log.info(
+        { path: updatesPath },
+        "Appended safe storage limits release note",
+      );
+    } catch (err) {
+      log.warn(
+        { err, path: updatesPath },
+        "Failed to append safe storage limits release note to UPDATES.md",
+      );
+    }
+  },
+
+  down(_workspaceDir: string): void {
+    // Forward-only: UPDATES.md is a user-facing bulletin the assistant
+    // processes and deletes on its own.
+  },
+};

package/src/workspace/migrations/068-release-notes-local-timezone.ts

@@ -0,0 +1,65 @@
+import {
+  appendFileSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import type { WorkspaceMigration } from "./types.js";
+
+const log = getLogger("workspace-migration-068-release-notes-local-timezone");
+
+const MIGRATION_ID = "068-release-notes-local-timezone";
+const MARKER = `<!-- release-note-id:${MIGRATION_ID} -->`;
+
+const RELEASE_NOTE = `${MARKER}
+## Local timezone grounding
+
+The assistant now grounds \`current_time\` in your local timezone across clients,
+instead of falling back to UTC when the client can report the device timezone.
+
+Manual timezone overrides still win when configured, and the assistant can help
+update a stale override after you confirm that your device timezone should be
+used going forward.
+`;
+
+export const releaseNotesLocalTimezoneMigration: WorkspaceMigration = {
+  id: MIGRATION_ID,
+  description:
+    "Append release notes for local timezone grounding to UPDATES.md",
+
+  run(workspaceDir: string): void {
+    const updatesPath = join(workspaceDir, "UPDATES.md");
+
+    try {
+      if (existsSync(updatesPath)) {
+        const existing = readFileSync(updatesPath, "utf-8");
+        if (existing.includes(MARKER)) {
+          return;
+        }
+        const needsLeadingNewline = !existing.endsWith("\n\n");
+        const prefix = existing.endsWith("\n") ? "\n" : "\n\n";
+        appendFileSync(
+          updatesPath,
+          needsLeadingNewline ? `${prefix}${RELEASE_NOTE}` : RELEASE_NOTE,
+          "utf-8",
+        );
+      } else {
+        writeFileSync(updatesPath, RELEASE_NOTE, "utf-8");
+      }
+      log.info({ path: updatesPath }, "Appended local timezone release note");
+    } catch (err) {
+      log.warn(
+        { err, path: updatesPath },
+        "Failed to append local timezone release note to UPDATES.md",
+      );
+    }
+  },
+
+  down(_workspaceDir: string): void {
+    // Forward-only: UPDATES.md is a user-facing bulletin the assistant
+    // processes and deletes on its own.
+  },
+};

package/src/workspace/migrations/AGENTS.md

@@ -6,6 +6,6 @@ Each migration file must be **fully self-contained**. All helper functions, cons
 
 - **No external exports.** Migration files must not export anything other than the single `WorkspaceMigration` object. Other code must never import from a migration file.
 - **Duplicate rather than share.** If two migrations need the same helper, duplicate it in both files. Migrations are write-once code — they run once per assistant and are never modified after release. Duplication is preferable to coupling.
-- **Allowed imports:** `./types.js` (for the `WorkspaceMigration` interface), `../../util/logger.js` (for structured logging), and Node/Bun runtime built-ins (`node:fs`, `node:path`, `node:crypto`, `bun:sqlite`, etc.). All other dependencies — both project-internal modules and third-party npm packages — must be inlined. Do not import from shared modules like `../../memory/` or `../../config/`, and do not add npm dependencies.
+- **Allowed imports:** `./types.js` (for the `WorkspaceMigration` interface), `./utils.js` (for shared path-resolution helpers like `getVellumRoot()`), `../../util/logger.js` (for structured logging), and Node/Bun runtime built-ins (`node:fs`, `node:path`, `node:crypto`, `bun:sqlite`, etc.). All other dependencies — both project-internal modules and third-party npm packages — must be inlined. Do not import from shared modules like `../../memory/` or `../../config/`, and do not add npm dependencies.
 - **Graceful on all platforms.** Migrations run on macOS, Linux, and in Docker. Platform-specific operations must no-op gracefully on unsupported platforms — never throw.
 - **Idempotent.** Migrations must be safe to re-run if interrupted. The runner checkpoints state as `"started"` before execution and `"completed"` after, so a crash mid-migration triggers a re-run on next startup.

package/src/workspace/migrations/migrate-to-workspace-volume.ts

@@ -2,7 +2,7 @@
  * Workspace migration: Migrate workspace data from /data to /workspace volume.
  *
  * In the old Docker volume layout, workspace data lived at
- * `$BASE_DATA_DIR/.vellum/workspace`. In the new layout, VELLUM_WORKSPACE_DIR points
+ * `<vellumRoot>/workspace`. In the new layout, VELLUM_WORKSPACE_DIR points
  * to a dedicated volume (e.g. `/workspace`). On first boot with the new layout,
  * this migration copies existing workspace data from the old location to the
  * new volume so nothing is lost.
@@ -24,6 +24,7 @@ import {
 import { join } from "node:path";
 
 import type { WorkspaceMigration } from "./types.js";
+import { getVellumRoot } from "./utils.js";
 
 const SENTINEL_FILENAME = ".workspace-volume-migrated";
 
@@ -68,15 +69,8 @@ export const migrateToWorkspaceVolumeMigration: WorkspaceMigration = {
       return;
     }
 
-    // Resolve the old workspace location: $BASE_DATA_DIR/.vellum/workspace
-    const baseDataDir = process.env.BASE_DATA_DIR?.trim() || undefined;
-    if (!baseDataDir) {
-      // No BASE_DATA_DIR means there's no old location to migrate from
-      writeSentinel(sentinelPath);
-      return;
-    }
-
-    const oldWorkspaceDir = join(baseDataDir, ".vellum", "workspace");
+    // Resolve the old workspace location: <vellumRoot>/workspace
+    const oldWorkspaceDir = join(getVellumRoot(), "workspace");
 
     // If the old workspace doesn't exist or is empty, nothing to migrate
     if (!existsSync(oldWorkspaceDir)) {

package/src/workspace/migrations/registry.ts

@@ -62,6 +62,10 @@ import { moveBackupKeyToWorkspaceMigration } from "./061-move-backup-key-to-work
 import { dropMemoryV2EdgesJsonMigration } from "./062-drop-memory-v2-edges-json.js";
 import { releaseNotesDynamicModelContextMigration } from "./063-release-notes-dynamic-model-context.js";
 import { unwindMainAgentOpusSeedMigration } from "./064-unwind-main-agent-opus-seed.js";
+import { bumpStaleHeartbeatIntervalMigration } from "./065-bump-stale-heartbeat-interval.js";
+import { seedHeartbeatCallsiteCostDefaultMigration } from "./066-seed-heartbeat-callsite-cost-default.js";
+import { releaseNotesSafeStorageLimitsMigration } from "./067-release-notes-safe-storage-limits.js";
+import { releaseNotesLocalTimezoneMigration } from "./068-release-notes-local-timezone.js";
 import { migrateToWorkspaceVolumeMigration } from "./migrate-to-workspace-volume.js";
 import type { WorkspaceMigration } from "./types.js";
 
@@ -135,4 +139,8 @@ export const WORKSPACE_MIGRATIONS: WorkspaceMigration[] = [
   dropMemoryV2EdgesJsonMigration,
   releaseNotesDynamicModelContextMigration,
   unwindMainAgentOpusSeedMigration,
+  bumpStaleHeartbeatIntervalMigration,
+  seedHeartbeatCallsiteCostDefaultMigration,
+  releaseNotesSafeStorageLimitsMigration,
+  releaseNotesLocalTimezoneMigration,
 ];

package/src/workspace/migrations/utils.ts

@@ -0,0 +1,21 @@
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * Resolve the legacy Vellum root directory (~/.vellum).
+ *
+ * Resolution order:
+ * 1. Parent of VELLUM_WORKSPACE_DIR — e.g. /data/.vellum/workspace → /data/.vellum
+ * 2. If that parent is "/" (workspace at top level, e.g. /workspace), fall back
+ *    to homedir()/.vellum
+ *
+ * This replaces the old inlined `getRootDir()` pattern used by individual migrations.
+ */
+export function getVellumRoot(): string {
+  const workspaceDir = process.env.VELLUM_WORKSPACE_DIR?.trim();
+  if (workspaceDir) {
+    const parent = dirname(workspaceDir);
+    if (parent !== "/") return parent;
+  }
+  return join(homedir(), ".vellum");
+}