@vellumai/assistant 0.8.5 → 0.8.7

package/src/util/platform.ts

@@ -2,6 +2,8 @@ import { chmodSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+import { SEEDS } from "@vellumai/environments";
+
 import { getWorkspaceDirOverride } from "../config/env-registry.js";
 
 /**
@@ -124,18 +126,19 @@ export function getAvatarImagePath(): string {
   return join(getAvatarDir(), AVATAR_IMAGE_FILENAME);
 }
 
-// Kept in sync with `cli/src/lib/environments/seeds.ts`. Drift between
-// these two sites is caught at test time by
-// `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
-// list into a `packages/environments` package so both sites import
-// from one place.
-const KNOWN_ENVIRONMENTS: ReadonlySet<string> = new Set([
-  "production",
-  "staging",
-  "test",
-  "dev",
-  "local",
-]);
+/** Canonical filename for the avatar state manifest. */
+export const AVATAR_MANIFEST_FILENAME = "avatar.json";
+
+/** Returns the canonical avatar manifest path (~/.vellum/workspace/data/avatar/avatar.json). */
+export function getAvatarManifestPath(): string {
+  return join(getAvatarDir(), AVATAR_MANIFEST_FILENAME);
+}
+
+// The set of known environment names, derived from the shared
+// `@vellumai/environments` seed table so this site can never drift from the
+// CLI. The Swift client mirrors the same list (it can't import TS); that
+// cross-language pair is guarded by `cli/src/__tests__/env-drift.test.ts`.
+const KNOWN_ENVIRONMENTS: ReadonlySet<string> = new Set(Object.keys(SEEDS));
 
 /**
  * Returns the env-scoped XDG config subdirectory name for Vellum

package/src/work-items/work-item-runner.ts

@@ -137,8 +137,13 @@ export function runWorkItemInBackground(workItemId: string): RunWorkItemResult {
             conversation.taskRunId = taskRunId;
             conversation.headlessLock = true;
           }
-          await conversation.processMessage(message, [], (event) => {
-            broadcastMessage(event);
+          await conversation.processMessage({
+            content: message,
+            attachments: [],
+            onEvent: (event) => {
+              broadcastMessage(event);
+            },
+            isInteractive: false,
           });
         },
       );

package/src/workspace/migrations/028-recover-conversations-from-disk-view.ts

@@ -133,9 +133,7 @@ export const recoverConversationsFromDiskViewMigration: WorkspaceMigration = {
       // Read and parse meta.json
       const metaPath = join(dirPath, "meta.json");
       if (!existsSync(metaPath)) {
-        log.warn(
-          `Skipping ${entry}: missing meta.json`,
-        );
+        log.warn(`Skipping ${entry}: missing meta.json`);
         skipped++;
         continue;
       }
@@ -144,17 +142,13 @@ export const recoverConversationsFromDiskViewMigration: WorkspaceMigration = {
       try {
         meta = JSON.parse(readFileSync(metaPath, "utf-8")) as DiskMeta;
       } catch (err) {
-        log.warn(
-          `Skipping ${entry}: malformed meta.json: ${err}`,
-        );
+        log.warn(`Skipping ${entry}: malformed meta.json: ${err}`);
         skipped++;
         continue;
       }
 
       if (!meta.id) {
-        log.warn(
-          `Skipping ${entry}: meta.json missing id`,
-        );
+        log.warn(`Skipping ${entry}: meta.json missing id`);
         skipped++;
         continue;
       }
@@ -182,9 +176,7 @@ export const recoverConversationsFromDiskViewMigration: WorkspaceMigration = {
             const trimmed = line.trim();
             if (!trimmed) continue;
             try {
-              messageRecords.push(
-                JSON.parse(trimmed) as DiskMessageRecord,
-              );
+              messageRecords.push(JSON.parse(trimmed) as DiskMessageRecord);
             } catch {
               log.warn(
                 `Skipping malformed JSONL line in ${entry}/messages.jsonl`,
@@ -192,9 +184,7 @@ export const recoverConversationsFromDiskViewMigration: WorkspaceMigration = {
             }
           }
         } catch (err) {
-          log.warn(
-            `Failed to read messages.jsonl for ${entry}: ${err}`,
-          );
+          log.warn(`Failed to read messages.jsonl for ${entry}: ${err}`);
         }
       }
 
@@ -231,8 +221,7 @@ export const recoverConversationsFromDiskViewMigration: WorkspaceMigration = {
 
           for (const record of messageRecords) {
             const contentBlocks = buildContentBlocks(record);
-            const msgCreatedAt =
-              parseEpochMs(record.ts) ?? createdAt;
+            const msgCreatedAt = parseEpochMs(record.ts) ?? createdAt;
 
             tx.insert(messages)
               .values({
@@ -249,9 +238,7 @@ export const recoverConversationsFromDiskViewMigration: WorkspaceMigration = {
 
         recovered++;
       } catch (err) {
-        log.warn(
-          `Failed to insert conversation ${meta.id} (${entry}): ${err}`,
-        );
+        log.warn(`Failed to insert conversation ${meta.id} (${entry}): ${err}`);
         errors++;
       }
     }

package/src/workspace/migrations/090-memory-router-cost-optimized-profile.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+// Flip callSites.memoryRouter from { profile: "balanced" } (the shape that
+// migration 087 wrote) to the shipped cost-optimized default so the router
+// rides the workspace's cheaper/faster managed profile.
+//
+// The migrated entry must mirror the shipped default in call-site-defaults.ts
+// EXACTLY — { profile: "cost-optimized", contextWindow: { maxInputTokens:
+// 1_000_000 } } — because the resolver prefers an explicit
+// llm.callSites.memoryRouter entry over CALL_SITE_DEFAULTS. Writing a bare
+// { profile: "cost-optimized" } would drop the 1M input window and regress
+// migrated users to the profile's normal ~200k window.
+//
+// The shipped default in call-site-defaults.ts also moves to cost-optimized
+// in the same change; this migration is what gets existing users — who carry
+// an explicit { profile: "balanced" } in their config.json — onto the new
+// default. Workspaces with no memoryRouter entry already pick up the shipped
+// default automatically (e.g. BYOK installs that skipped 077/087, or fresh
+// installs), so this migration only touches the 087-seeded balanced shape and
+// the bare { profile: "cost-optimized" } shape an earlier (pre-fix) run of
+// this migration may have written — the latter so those users also recover
+// the 1M window.
+//
+// Two skip conditions, mirroring 087:
+//
+//   1. BYOK / non-Anthropic workspaces. `cost-optimized` is a managed
+//      Anthropic profile, which off-platform installs disable. Forcing it
+//      there would make getConfiguredProvider("memoryRouter") return null
+//      and silently disable memory injection. Detect via llm.default.provider.
+//
+//   2. User-customized memoryRouter config. If the existing entry carries any
+//      key beyond a bare balanced/cost-optimized profile reference, the user —
+//      or a platform overlay — chose those values deliberately. Preserve them.
+const MEMORY_ROUTER_COST_OPTIMIZED = {
+  profile: "cost-optimized",
+  contextWindow: { maxInputTokens: 1_000_000 },
+} as const;
+
+export const memoryRouterCostOptimizedProfileMigration: WorkspaceMigration = {
+  id: "090-memory-router-cost-optimized-profile",
+  description:
+    "Set callSites.memoryRouter to the shipped cost-optimized default (with 1M context) for workspaces still carrying the 087-seeded balanced profile",
+  run(workspaceDir: string): void {
+    if (process.env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH) return;
+
+    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 llm = readObject(config.llm);
+    if (llm === null) return;
+
+    const explicitProvider = readString(readObject(llm.default)?.provider);
+    if (explicitProvider !== undefined && explicitProvider !== "anthropic") {
+      return;
+    }
+
+    const callSites = readObject(llm.callSites);
+    if (callSites === null) return;
+
+    const existing = readObject(callSites.memoryRouter);
+    if (existing === null || !needsCostOptimizedUpgrade(existing)) return;
+
+    callSites.memoryRouter = { ...MEMORY_ROUTER_COST_OPTIMIZED };
+    llm.callSites = callSites;
+    config.llm = llm;
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  },
+  down(_workspaceDir: string): void {
+    // Forward-only.
+  },
+};
+
+// True when the entry is a bare single-key profile reference we own:
+//   - { profile: "balanced" }       — what migration 087 wrote
+//   - { profile: "cost-optimized" } — what a pre-fix run of THIS migration
+//                                      wrote (no contextWindow), so those users
+//                                      still recover the 1M window
+// Any extra keys (model pins, tuning fields, an already-present contextWindow)
+// mean the user/platform customized it — preserve and skip. This keeps the
+// migration idempotent: once it writes the full cost-optimized + contextWindow
+// shape, the two-key entry no longer matches.
+function needsCostOptimizedUpgrade(entry: Record<string, unknown>): boolean {
+  const keys = Object.keys(entry);
+  if (keys.length !== 1) return false;
+  return entry.profile === "balanced" || entry.profile === "cost-optimized";
+}
+
+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/091-retighten-migration-onboarding-thread.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { MigrationRunContext, WorkspaceMigration } from "./types.js";
+
+// The exact onboarding bullet seeded by 069-seed-onboarding-threads for the
+// assistant-migration step. Inlined here (not imported) to keep this migration
+// self-contained and decoupled from 069.
+const OLD_BULLET =
+  "- Ask your user if they use ChatGPT, Claude or another AI tool and offer to help them import memories from there.";
+
+// The tightened replacement: help-first, an early light one-time offer, naming
+// the common prior assistants. Keeps the literal "ChatGPT, Claude" substring.
+const NEW_BULLET =
+  "- After helping with the user's first real task, offer early — at the first natural opening — to port their context, memories, prompts, skills, or workflows from a prior assistant (ChatGPT, Claude, OpenClaw, Hermes, or another tool). Keep it a light one-time offer, not a push; if they decline, drop it.";
+
+export const retightenMigrationOnboardingThreadMigration: WorkspaceMigration = {
+  id: "091-retighten-migration-onboarding-thread",
+  description:
+    "Retighten the assistant-migration onboarding bullet in memory/threads.md for brand new assistants",
+
+  run(workspaceDir: string, ctx?: MigrationRunContext): void {
+    // Only rewrite onboarding tasks for newly-created workspaces. An existing
+    // assistant whose user has edited threads.md must not have its content
+    // rewritten on upgrade. When invoked without a context (e.g. from older
+    // callers), default to the safe path and skip — the runner always supplies
+    // one in production.
+    if (!ctx?.isNewWorkspace) return;
+    const filePath = join(workspaceDir, "memory", "threads.md");
+    if (!existsSync(filePath)) return;
+    const content = readFileSync(filePath, "utf-8");
+    // Idempotent: if the old bullet is absent (already replaced, or the user
+    // edited it away), there is nothing to do.
+    if (!content.includes(OLD_BULLET)) return;
+    writeFileSync(filePath, content.replace(OLD_BULLET, NEW_BULLET), "utf-8");
+  },
+
+  down(_workspaceDir: string): void {
+    // Forward-only: never rewrite user-visible memory content on rollback.
+  },
+};

package/src/workspace/migrations/092-backfill-v3-leaves.ts

@@ -0,0 +1,169 @@
+import * as fs from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * v3 leaf assignments and concept pages, addressed relative to the workspace.
+ */
+const ASSIGNMENTS_REL = join("memory", "v3", "data", "assignments.json");
+const CONCEPTS_REL = join("memory", "concepts");
+
+const FRONTMATTER_DELIMITER = "---";
+
+/**
+ * Read the v3 slug -> leaf-path assignment map from the workspace data dir.
+ *
+ * Returns an empty map when `assignments.json` is absent (the v3 data dir was
+ * never materialized for this workspace) so the migration is a clean no-op.
+ */
+function readAssignments(workspaceDir: string): Record<string, string[]> {
+  const assignmentsPath = join(workspaceDir, ASSIGNMENTS_REL);
+  let raw: string;
+  try {
+    raw = fs.readFileSync(assignmentsPath, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw err;
+  }
+  const parsed = JSON.parse(raw) as unknown;
+  return parsed && typeof parsed === "object"
+    ? (parsed as Record<string, string[]>)
+    : {};
+}
+
+interface SplitPage {
+  /** Raw YAML frontmatter block (between the `---` fences), without fences. */
+  frontmatter: string;
+  /** Everything after the closing frontmatter fence, verbatim. */
+  body: string;
+}
+
+/**
+ * Split a concept page into its YAML frontmatter block and body. Returns `null`
+ * when the file does not open with a `---` frontmatter fence (a page with no
+ * frontmatter, which we leave untouched).
+ *
+ * Inlined here rather than importing `../v2/page-store` — workspace migrations
+ * must stay self-contained (see AGENTS.md) so an append-only migration never
+ * shifts semantics when the runtime page parser evolves.
+ */
+function splitFrontmatter(content: string): SplitPage | null {
+  if (!content.startsWith(FRONTMATTER_DELIMITER)) return null;
+  const afterOpen = content.slice(FRONTMATTER_DELIMITER.length);
+  const closeMatch = afterOpen.match(/\r?\n---[ \t]*(?:\r?\n|$)/);
+  if (!closeMatch || closeMatch.index === undefined) return null;
+  const frontmatter = afterOpen.slice(0, closeMatch.index);
+  const body = afterOpen.slice(closeMatch.index + closeMatch[0].length);
+  return { frontmatter, body };
+}
+
+/**
+ * Locate a top-level `leaves:` field in the frontmatter lines: the index of its
+ * key line plus the (exclusive) index after any indented block-sequence items
+ * that belong to it. Returns `null` when no `leaves:` key is present.
+ *
+ * A line-shaped scan (rather than a YAML parse) keeps the migration free of an
+ * npm dependency, as AGENTS.md requires; leaf frontmatter is flat key/value so
+ * the only nesting is a `leaves:` block sequence (`  - path`).
+ */
+function findLeavesField(
+  lines: string[],
+): { start: number; end: number; nonEmpty: boolean } | null {
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^leaves:[ \t]*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const inline = m[1].trim();
+    if (inline.length > 0) {
+      // Inline form: `leaves: [a, b]` (non-empty) or `leaves: []` (empty).
+      return { start: i, end: i + 1, nonEmpty: inline !== "[]" };
+    }
+    // Block form: consume following indented lines (`  - item`) as the value.
+    let end = i + 1;
+    let nonEmpty = false;
+    while (end < lines.length && /^[ \t]+\S/.test(lines[end])) {
+      if (/^[ \t]+-[ \t]+\S/.test(lines[end])) nonEmpty = true;
+      end++;
+    }
+    return { start: i, end, nonEmpty };
+  }
+  return null;
+}
+
+/**
+ * Splice a non-empty `leaves:` block sequence into the frontmatter, replacing
+ * any existing (empty) `leaves:` field in place so we never leave a duplicate
+ * key. Leaf paths are simple slugs (`domain/topic`) that need no quoting; we
+ * still defensively quote any value containing YAML-significant characters.
+ */
+function withLeaves(frontmatter: string, leaves: string[]): string {
+  const quote = (v: string): string =>
+    /[:#[\]{}",&*!|>%@`]/.test(v) ? JSON.stringify(v) : v;
+  const block = ["leaves:", ...leaves.map((l) => `  - ${quote(l)}`)];
+
+  const lines = frontmatter.replace(/\s+$/, "").split(/\r?\n/);
+  // Drop a leading empty line so a previously blank frontmatter doesn't yield
+  // a stray newline at the top.
+  while (lines.length > 0 && lines[0].trim() === "") lines.shift();
+
+  const existing = findLeavesField(lines);
+  if (existing) {
+    lines.splice(existing.start, existing.end - existing.start, ...block);
+  } else {
+    lines.push(...block);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Backfill `leaves:` into concept-page frontmatter from the v3 assignment map.
+ *
+ * v3 routing persists a slug -> leaf-path map at
+ * `<workspace>/memory/v3/data/assignments.json`. Concept pages gained an
+ * optional `leaves` frontmatter field, but existing pages predate it. This
+ * one-time migration copies each slug's assignment into the matching page's
+ * frontmatter.
+ *
+ * Idempotent: pages that already carry a non-empty `leaves` are left untouched
+ * (never clobbered). A missing `assignments.json` or a slug with no matching
+ * page is a no-op — neither throws. All read/write logic is inlined (built-ins
+ * only) so the migration stays self-contained per AGENTS.md.
+ */
+export const backfillV3LeavesMigration: WorkspaceMigration = {
+  id: "092-backfill-v3-leaves",
+  description: "Backfill v3 leaf assignments into concept-page frontmatter",
+
+  run(workspaceDir: string): void {
+    const assignments = readAssignments(workspaceDir);
+    const conceptsDir = join(workspaceDir, CONCEPTS_REL);
+
+    for (const [slug, leaves] of Object.entries(assignments)) {
+      if (!Array.isArray(leaves) || leaves.length === 0) continue;
+
+      const file = join(conceptsDir, `${slug}.md`);
+      let content: string;
+      try {
+        content = fs.readFileSync(file, "utf8");
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+        throw err;
+      }
+
+      const split = splitFrontmatter(content);
+      if (!split) continue; // No frontmatter fence — leave the page untouched.
+      // Never clobber a page that already declares non-empty leaves.
+      const existing = findLeavesField(split.frontmatter.split(/\r?\n/));
+      if (existing?.nonEmpty) continue;
+
+      const rebuilt = `${FRONTMATTER_DELIMITER}\n${withLeaves(
+        split.frontmatter,
+        leaves,
+      )}\n${FRONTMATTER_DELIMITER}\n${split.body}`;
+      fs.writeFileSync(file, rebuilt, "utf8");
+    }
+  },
+
+  down(): void {
+    // no-op: `leaves` is an additive field; removing it would lose data.
+  },
+};

package/src/workspace/migrations/093-backfill-leaf-ids.ts

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import { join, relative } from "node:path";
+
+import { getLogger } from "../../util/logger.js";
+import type { WorkspaceMigration } from "./types.js";
+
+const log = getLogger("workspace-migration-093-backfill-leaf-ids");
+
+/** v3 leaf files live under this path relative to the workspace dir. */
+const LEAVES_REL = join("memory", "v3", "data", "leaves");
+
+const FRONTMATTER_DELIMITER = "---";
+
+interface SplitLeaf {
+  /** Raw YAML frontmatter block (between the `---` fences), without fences. */
+  frontmatter: string;
+  /** Everything after the closing frontmatter fence, verbatim. */
+  body: string;
+}
+
+/**
+ * Split a leaf `.md` file into its YAML frontmatter block and body. Returns
+ * `null` when the file does not open with a `---` frontmatter fence, so callers
+ * can skip files that are not well-formed leaves (we never rewrite those).
+ */
+function splitFrontmatter(content: string): SplitLeaf | null {
+  if (!content.startsWith(FRONTMATTER_DELIMITER)) return null;
+  // Skip the opening fence and find the closing one at the start of a line.
+  const afterOpen = content.slice(FRONTMATTER_DELIMITER.length);
+  const closeMatch = afterOpen.match(/\r?\n---[ \t]*(?:\r?\n|$)/);
+  if (!closeMatch || closeMatch.index === undefined) return null;
+  const frontmatter = afterOpen.slice(0, closeMatch.index);
+  const body = afterOpen.slice(closeMatch.index + closeMatch[0].length);
+  return { frontmatter, body };
+}
+
+/**
+ * Deterministic, stable id derived from the leaf's relative path at backfill
+ * time. The same path always yields the same id, so re-runs and re-installs
+ * converge. 12 hex chars (48 bits) is ample to avoid collisions across the
+ * handful-to-thousands of leaves a workspace holds.
+ */
+function stableIdForPath(relPath: string): string {
+  return createHash("sha256").update(relPath).digest("hex").slice(0, 12);
+}
+
+/** Recursively collect every `.md` file under `dir`. */
+function collectLeafFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...collectLeafFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * True when the frontmatter already declares a non-empty top-level `id:` field.
+ * A line-shaped check (rather than a YAML parse) keeps the migration free of an
+ * npm `yaml` dependency, as AGENTS.md requires — leaf frontmatter is simple
+ * flat key/value, so a `^id:` scan is sufficient and durable.
+ */
+function hasStableId(frontmatter: string): boolean {
+  for (const line of frontmatter.split(/\r?\n/)) {
+    const m = /^id:[ \t]*(.*)$/.exec(line);
+    if (!m) continue;
+    return m[1].trim().replace(/^["']|["']$/g, "").length > 0;
+  }
+  return false;
+}
+
+/**
+ * Backfill a stable `id` into the frontmatter of `file` if it lacks one.
+ * Returns `true` when the file was rewritten. Idempotent: a leaf that already
+ * has an `id` is left untouched. The id is keyed off the leaf's path relative
+ * to the leaves root so it is stable across machines and re-runs.
+ *
+ * Frontmatter is edited as text (the `id:` line is prepended to the existing
+ * block) rather than parsed/re-serialized through a YAML library: workspace
+ * migrations must stay self-contained with no npm deps (AGENTS.md), and a
+ * text splice also preserves the rest of the human-authored frontmatter
+ * verbatim (key order, comments, formatting).
+ */
+function backfillLeaf(leavesDir: string, file: string): boolean {
+  const content = fs.readFileSync(file, "utf8");
+  const split = splitFrontmatter(content);
+  if (!split) {
+    log.warn({ file }, "Leaf file missing YAML frontmatter; skipping");
+    return false;
+  }
+
+  if (hasStableId(split.frontmatter)) {
+    return false; // Already has a stable id — idempotent skip.
+  }
+
+  const relPath = relative(leavesDir, file);
+  const idLine = `id: ${stableIdForPath(relPath)}`;
+  const existing = split.frontmatter.replace(/^\s+|\s+$/g, "");
+  const newFrontmatter =
+    existing.length > 0 ? `${idLine}\n${existing}` : idLine;
+  const rebuilt = `${FRONTMATTER_DELIMITER}\n${newFrontmatter}\n${FRONTMATTER_DELIMITER}\n${split.body}`;
+  fs.writeFileSync(file, rebuilt, "utf8");
+  return true;
+}
+
+/**
+ * Backfill a stable `id` into every v3 leaf's frontmatter.
+ *
+ * v3 leaves are addressed by their on-disk `path`, which moves as the tree is
+ * reorganized. A stable `id` gives downstream self-maintenance machinery a
+ * durable handle that survives path churn. The id is a short hash of the leaf's
+ * relative path at backfill time — deterministic, so re-runs and fresh installs
+ * converge — and existing ids are preserved.
+ */
+export const backfillLeafIdsMigration: WorkspaceMigration = {
+  id: "092-backfill-leaf-ids",
+  description: "Backfill a stable id into every v3 leaf's frontmatter",
+  retryFailedCheckpoint: true,
+
+  run(workspaceDir: string): void {
+    const leavesDir = join(workspaceDir, LEAVES_REL);
+    if (!fs.existsSync(leavesDir)) return; // No v3 leaves yet — no-op.
+
+    let rewritten = 0;
+    for (const file of collectLeafFiles(leavesDir)) {
+      if (backfillLeaf(leavesDir, file)) rewritten += 1;
+    }
+    if (rewritten > 0) {
+      log.info(
+        { rewritten, leavesDir },
+        "Backfilled stable ids into v3 leaves",
+      );
+    }
+  },
+
+  // No-op: stripping ids would discard the durable handles other code now
+  // relies on. A backfilled id is harmless to leave in place on rollback.
+  down(): void {},
+};