@vellumai/assistant 0.8.6 → 0.8.7

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

@@ -8,12 +8,21 @@
  */
 
 import { RiskLevel } from "../../permissions/types.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+const APP_BUILDER_ARTIFACT_RE =
+  /\b(app|apps|application|applications|website|websites|site|sites|dashboard|dashboards|game|games|calculator|calculators|tracker|trackers|visualization|visualizations|visualisation|visualisations|tool|tools|utility|utilities|counter|counters)\b/i;
+const APP_BUILDER_BUILD_RE =
+  /\b(build|building|built|create|creating|created|make|making|made|generate|generating|generated)\b/i;
+
 /**
  * Forward execution to the connected macOS client via the request-bound
  * `proxyToolResolver`. Returns a structured error when no resolver is
@@ -25,6 +34,14 @@ function proxyExecute(toolName: string) {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> => {
+    if (toolName === "ui_show" && isDynamicPageAppSubstitute(input)) {
+      return {
+        content:
+          'Error: ui_show dynamic_page is for transient UI surfaces only. This request is building an app-like experience, so load the app-builder skill first with `skill_load` using `skill: "app-builder"`, then create a persistent Library app with the app-builder workflow.',
+        isError: true,
+      };
+    }
+
     if (!context.proxyToolResolver) {
       return {
         content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires an external resolver (e.g. a connected macOS client).`,
@@ -35,14 +52,57 @@ function proxyExecute(toolName: string) {
   };
 }
 
+function isDynamicPageAppSubstitute(input: Record<string, unknown>): boolean {
+  if (input.surface_type !== "dynamic_page") {
+    return false;
+  }
+
+  const text = collectRoutingText(input).join(" ");
+  if (!APP_BUILDER_ARTIFACT_RE.test(text)) {
+    return false;
+  }
+
+  return APP_BUILDER_BUILD_RE.test(text) || /\b(app|application)\b/i.test(text);
+}
+
+function collectRoutingText(input: Record<string, unknown>): string[] {
+  const values: string[] = [];
+  addString(values, input.title);
+  addString(values, input.activity);
+
+  const data = asRecord(input.data);
+  if (data) {
+    const preview = asRecord(data.preview);
+    if (preview) {
+      addString(values, preview.title);
+      addString(values, preview.subtitle);
+      addString(values, preview.description);
+    }
+  }
+
+  return values;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function addString(values: string[], value: unknown): void {
+  if (typeof value === "string") {
+    values.push(value);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // ui_show
 // ---------------------------------------------------------------------------
 
-export const uiShowTool: Tool = {
+export const uiShowTool = {
   name: "ui_show",
   description:
-    "Surface structured data or UI in the conversation. For long-form writing use the document skill; for interactive apps use the app-builder skill.\n\n" +
+    'Surface structured data or UI in the conversation. For long-form writing use the document skill. For interactive apps, dashboards, games, calculators, or durable tools, call `skill_load` with `skill: "app-builder"` and use the app-builder workflow; do not use `dynamic_page` as a substitute for a persistent app. App-like `dynamic_page` calls are rejected.\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' +
     '- table: { columns: [{ id, label }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
@@ -121,13 +181,13 @@ export const uiShowTool: Tool = {
   },
 
   execute: proxyExecute("ui_show"),
-};
+} satisfies ToolDefinition;
 
 // ---------------------------------------------------------------------------
 // ui_update
 // ---------------------------------------------------------------------------
 
-const uiUpdateTool: Tool = {
+const uiUpdateTool = {
   name: "ui_update",
   description:
     "Update an existing surface's data. The provided data object is merged into the surface's current data.\n" +
@@ -152,13 +212,13 @@ const uiUpdateTool: Tool = {
   },
 
   execute: proxyExecute("ui_update"),
-};
+} satisfies ToolDefinition;
 
 // ---------------------------------------------------------------------------
 // ui_dismiss
 // ---------------------------------------------------------------------------
 
-const uiDismissTool: Tool = {
+const uiDismissTool = {
   name: "ui_dismiss",
   description: "Dismiss a currently displayed surface.",
   category: "ui-surface",
@@ -177,9 +237,9 @@ const uiDismissTool: Tool = {
   },
 
   execute: proxyExecute("ui_dismiss"),
-};
+} satisfies ToolDefinition;
 
-export const allUiSurfaceTools: Tool[] = [
+export const allUiSurfaceTools: ToolDefinition[] = [
   uiShowTool,
   uiUpdateTool,
   uiDismissTool,

package/src/usage/types.ts

@@ -85,4 +85,14 @@ export interface UsageEvent extends UsageEventInput {
   inferenceProfileSource: UsageAttributionProfileSource | null;
   estimatedCostUsd: number | null;
   pricingStatus: "priced" | "unpriced";
+  /**
+   * Version of the assistant binary at the moment this event was
+   * RECORDED, captured by `recordUsageEvent` and persisted with the
+   * row. Not provided by callers; computed at record time. Surfaces
+   * onto the telemetry wire as `assistant_version` so analytics
+   * stays truthful even when a batch flushes days after the events
+   * fired. `null` only for rows persisted before migration 267 ran.
+   * See `migrations/267-llm-usage-events-add-assistant-version.ts`.
+   */
+  assistantVersion: string | null;
 }

package/src/util/errors.ts

@@ -153,14 +153,14 @@ export class ConfigError extends AssistantError {
 export class ProviderNotConfiguredError extends ConfigError {
   /**
    * Optional name of the `provider_connections` row whose credential was
-   * missing. Surfaced through `ConversationErrorMessage.connectionName` so
+   * missing. Surfaced through `ConversationErrorEvent.connectionName` so
    * the macOS chat banner can render "API key required for connection
    * <name>" instead of a generic message.
    */
   public readonly connectionName?: string;
   /**
    * Optional name of the resolved profile in play when this error was
-   * thrown. Forwarded to the wire `ConversationErrorMessage.profileName`
+   * thrown. Forwarded to the wire `ConversationErrorEvent.profileName`
    * for the same banner-attribution purpose as `connectionName`.
    */
   public readonly profileName?: string;

package/src/util/map-limit.ts

@@ -0,0 +1,27 @@
+/**
+ * Map `fn` over `items` with bounded concurrency, preserving input order in the
+ * result array. At most `limit` invocations of `fn` are in flight at once.
+ *
+ * Each of the `min(limit, items.length)` workers pulls the next index off a
+ * shared cursor and processes it, so faster items don't block on slower ones.
+ * Results are written back to their original positions, so `out[i]` always
+ * corresponds to `items[i]` regardless of completion order.
+ */
+export async function mapLimit<T, R>(
+  items: T[],
+  limit: number,
+  fn: (t: T) => Promise<R>,
+): Promise<R[]> {
+  const out: R[] = new Array(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(limit, items.length) }, async () => {
+      while (true) {
+        const i = next++;
+        if (i >= items.length) return;
+        out[i] = await fn(items[i]!);
+      }
+    }),
+  );
+  return out;
+}

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/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 {},
+};