@vellumai/assistant 0.10.9-staging.1 → 0.10.9

package/src/plugins/defaults/memory/graph-topology/__tests__/build-memory-graph.test.ts

@@ -4,7 +4,10 @@ import type { PageIndexEntry } from "../../v2/page-index.js";
 import type { Slug } from "../../v3/types.js";
 import { assembleMemoryGraph } from "../build-memory-graph.js";
 
-function entry(slug: string, over: Partial<PageIndexEntry> = {}): PageIndexEntry {
+function entry(
+  slug: string,
+  over: Partial<PageIndexEntry> = {},
+): PageIndexEntry {
   return {
     id: 0,
     slug,
@@ -40,7 +43,9 @@ describe("assembleMemoryGraph", () => {
         entry("skills/agent-mail", { modifiedAt: 0 }),
         entry("send-email", { modifiedAt: 0 }),
       ],
-      staticAdjacency: adjacency([["my-concept", "skills/agent-mail", undefined]]),
+      staticAdjacency: adjacency([
+        ["my-concept", "skills/agent-mail", undefined],
+      ]),
     });
 
     const byId = new Map(nodes.map((n) => [n.id, n]));
@@ -127,4 +132,78 @@ describe("assembleMemoryGraph", () => {
       expect(nodes.some((n) => n.id === edge.target)).toBe(true);
     }
   });
+
+  it("prunes disconnected functionality nodes but keeps connected ones and all concepts", () => {
+    const { nodes } = assembleMemoryGraph({
+      entries: [
+        entry("lonely-concept"), // concept, degree 0 → kept
+        entry("linked-concept"), // concept, links to a skill
+        entry("skills/connected", { modifiedAt: 0 }), // skill, degree 1 → kept
+        entry("skills/orphan", { modifiedAt: 0 }), // skill, degree 0 → pruned
+        entry("cli-commands/orphan", { modifiedAt: 0 }), // capability, degree 0 → pruned
+      ],
+      staticAdjacency: adjacency([
+        ["linked-concept", "skills/connected", undefined],
+      ]),
+      pruneDisconnectedNonConcepts: true,
+    });
+
+    expect(nodes.map((n) => n.id).sort()).toEqual([
+      "linked-concept",
+      "lonely-concept",
+      "skills/connected",
+    ]);
+  });
+
+  it("keeps disconnected functionality nodes when pruning is off (default)", () => {
+    const { nodes } = assembleMemoryGraph({
+      entries: [entry("a"), entry("skills/orphan", { modifiedAt: 0 })],
+      staticAdjacency: adjacency([]),
+    });
+    expect(nodes.map((n) => n.id).sort()).toEqual(["a", "skills/orphan"]);
+  });
+
+  it("re-prunes a functionality node stranded by truncation", () => {
+    const { nodes, edges, truncated } = assembleMemoryGraph({
+      entries: [
+        entry("hub"),
+        entry("h1"),
+        entry("h2"),
+        entry("h3"),
+        entry("p"),
+        entry("q"),
+        entry("skills/s", { modifiedAt: 0 }),
+      ],
+      // hub has degree 3; skills/s has degree 2 (p, q). The cap keeps the top 2
+      // by degree (hub, skills/s) but drops every one of skills/s's neighbors.
+      staticAdjacency: adjacency([
+        ["hub", "h1", undefined],
+        ["hub", "h2", undefined],
+        ["hub", "h3", undefined],
+        ["skills/s", "p", undefined],
+        ["skills/s", "q", undefined],
+      ]),
+      maxNodes: 2,
+      pruneDisconnectedNonConcepts: true,
+    });
+
+    expect(truncated).toBe(true);
+    // skills/s survived the cap but lost both neighbors → re-pruned as isolated;
+    // the isolated concept hub is kept (concepts always survive).
+    expect(nodes.map((n) => n.id)).toEqual(["hub"]);
+    expect(edges).toEqual([]);
+  });
+
+  it("treats a real page under a reserved prefix as a concept, not a prunable skill", () => {
+    // A non-colliding user page like `skills/my-notes` survives the page index
+    // with a real mtime; it must classify as a concept (by modifiedAt, not the
+    // slug prefix) and therefore never be pruned as a disconnected skill.
+    const { nodes } = assembleMemoryGraph({
+      entries: [entry("skills/my-notes", { modifiedAt: 5 })],
+      staticAdjacency: adjacency([]),
+      pruneDisconnectedNonConcepts: true,
+    });
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]).toMatchObject({ id: "skills/my-notes", kind: "concept" });
+  });
 });

package/src/plugins/defaults/memory/graph-topology/build-memory-graph.ts

@@ -22,7 +22,10 @@ import { getWorkspaceDir } from "../paths.js";
 import { getPageIndex, type PageIndexEntry } from "../v2/page-index.js";
 import { readPage, renderPageContent } from "../v2/page-store.js";
 import { isSkillSlug } from "../v2/skill-store.js";
-import { isCapabilitySlug } from "../v3/capabilities.js";
+import {
+  isCapabilitySlug,
+  renderCapabilityContent,
+} from "../v3/capabilities.js";
 import { buildEdgeGraph } from "../v3/edge.js";
 import { computeLearnedEdgeGraph } from "../v3/learned-edges.js";
 import type { Slug } from "../v3/types.js";
@@ -78,24 +81,18 @@ function humanizeSlug(slug: string): string {
   return words.replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
-/** Node taxonomy tag used for coloring. Synthetic capability slugs (skills /
- * CLI commands) carry `modifiedAt: 0`; real concept pages carry a file mtime. */
+/** Node taxonomy tag used for coloring. Only synthetic rows (`modifiedAt: 0`)
+ * are functionality: skills carry the `skills/` prefix, other synthetics (CLI
+ * commands) are capabilities. A real on-disk page keeps a file mtime and is a
+ * concept even when it happens to sit under a reserved prefix (e.g. a user page
+ * `skills/my-notes` with no matching skill survives the page index). */
 function nodeKind(entry: PageIndexEntry): string {
-  if (isSkillSlug(entry.slug)) {
-    return "skill";
-  }
   if (entry.modifiedAt <= 0) {
-    return "capability";
+    return isSkillSlug(entry.slug) ? "skill" : "capability";
   }
   return "concept";
 }
 
-/** A real concept page: on-disk (has an mtime) and not a synthetic skill or
- * CLI-command capability slug. The graph shows concepts only. */
-function isConceptEntry(entry: PageIndexEntry): boolean {
-  return entry.modifiedAt > 0 && !isCapabilitySlug(entry.slug);
-}
-
 export interface AssembleMemoryGraphInput {
   /** Every article node in the corpus (page-index entries). */
   entries: readonly PageIndexEntry[];
@@ -105,6 +102,12 @@ export interface AssembleMemoryGraphInput {
   learnedAdjacency?: Adjacency;
   /** Node cap; defaults to {@link DEFAULT_MAX_NODES}. */
   maxNodes?: number;
+  /**
+   * When set, drop functionality nodes (kind `skill` / `capability`) that ended
+   * up with no edges — a skill nobody links to or co-selects is inert clutter.
+   * Concept nodes are always kept, even when isolated.
+   */
+  pruneDisconnectedNonConcepts?: boolean;
 }
 
 /**
@@ -199,6 +202,12 @@ export function assembleMemoryGraph(input: AssembleMemoryGraphInput): {
     return node;
   });
 
+  // Prune disconnected functionality nodes (see the option's doc). `weight` is
+  // the node's degree, so weight 0 ⇒ no incident edges ⇒ no edge cleanup needed.
+  if (input.pruneDisconnectedNonConcepts) {
+    nodes = nodes.filter((n) => n.kind === "concept" || (n.weight ?? 0) > 0);
+  }
+
   if (nodes.length <= maxNodes) {
     return { nodes, edges };
   }
@@ -211,6 +220,20 @@ export function assembleMemoryGraph(input: AssembleMemoryGraphInput): {
   const keptEdges = edges.filter(
     (e) => kept.has(e.source) && kept.has(e.target),
   );
+
+  // Truncation can strand a functionality node whose only neighbors were
+  // dropped. Re-prune against post-truncation degree so the connected-only
+  // guarantee holds even in a capped graph. An isolated node touches no kept
+  // edge by definition, so no further edge cleanup is needed.
+  if (input.pruneDisconnectedNonConcepts) {
+    const connected = new Set<string>();
+    for (const e of keptEdges) {
+      connected.add(e.source);
+      connected.add(e.target);
+    }
+    nodes = nodes.filter((n) => n.kind === "concept" || connected.has(n.id));
+  }
+
   return { nodes, edges: keptEdges, truncated: true };
 }
 
@@ -228,15 +251,28 @@ export async function getMemoryGraph(
 
   const workspaceDir = getWorkspaceDir();
   const pageIndex = await getPageIndex(workspaceDir);
-  // Concepts only: exclude synthetic skill / CLI-command slugs so the graph is
-  // purely the assistant's learned/authored concept pages. Edges to excluded
-  // slugs drop out downstream because they aren't in the node set.
-  const conceptEntries = pageIndex.entries.filter(isConceptEntry);
+  // Concepts plus functionality (skills / CLI-command capabilities). Feeding the
+  // full set to the edge builders is what lets a concept's `[[skills/foo]]` link
+  // and skill↔concept co-selections resolve to real edges — buildEdgeGraph and
+  // computeLearnedEdgeGraph both drop endpoints outside the set they're given.
+  // Functionality nodes that end up disconnected are pruned in assembleMemoryGraph.
+  const entries = pageIndex.entries;
+
+  // Synthetic rows (skills / CLI commands) carry `modifiedAt: 0` and have no
+  // on-disk page. Keyed by slug (not prefix) so a real user page that happens
+  // to live under a reserved prefix is NOT mistaken for a synthetic one.
+  const syntheticSlugs = new Set(
+    entries.filter((e) => e.modifiedAt <= 0).map((e) => e.slug),
+  );
 
   // Raw (frontmatter + body) page reader, matching the v3 lane build. A read
   // that rejects drops that article's authored/wikilink edges but keeps its
-  // numeric fallbacks.
+  // numeric fallbacks. Synthetic capability rows have no page, so short-circuit
+  // their guaranteed-miss read; a real page is read so its links are captured.
   const pageRaw = async (slug: Slug): Promise<string> => {
+    if (syntheticSlugs.has(slug)) {
+      return "";
+    }
     const page = await readPage(workspaceDir, slug);
     if (!page) {
       throw new Error(`page not found: ${slug}`);
@@ -244,7 +280,7 @@ export async function getMemoryGraph(
     return renderPageContent(page);
   };
 
-  const staticGraph = await buildEdgeGraph(conceptEntries, pageRaw, {
+  const staticGraph = await buildEdgeGraph(entries, pageRaw, {
     hubDegree: config.memory.v3.edge.hubDegree,
   });
 
@@ -265,39 +301,50 @@ export async function getMemoryGraph(
       maxPerPage: Math.max(learned.maxPerPage, GRAPH_LEARNED_MIN_MAX_PER_PAGE),
       now: Date.now(),
       windowMs: LEARNED_EDGES_WINDOW_DAYS * DAY_MS,
-      knownSlugs: new Set(conceptEntries.map((e) => e.slug)),
+      knownSlugs: new Set(entries.map((e) => e.slug)),
     },
   );
 
   const assembled = assembleMemoryGraph({
-    entries: conceptEntries,
+    entries,
     staticAdjacency: staticGraph.adjacency,
     learnedAdjacency: learnedGraph.adjacency,
+    pruneDisconnectedNonConcepts: true,
   });
 
   return { backend: BACKEND_MEMORY_V3, supported: true, ...assembled };
 }
 
 /**
- * Fetch a single concept node's content (its markdown body) by id. Used when a
- * user opens a node in the graph. Concepts only — skill/capability slugs and
- * unreadable pages return `{ found: false }`.
+ * Fetch a single node's content by id. Used when a user opens a node in the
+ * graph. Concept nodes return their page's markdown body; functionality nodes
+ * (skills / CLI commands) return the rendered capability statement. Unknown or
+ * unreadable ids return `{ found: false }`.
  */
 export async function getMemoryGraphNode(
   config: AssistantConfig,
   id: string,
 ): Promise<MemoryGraphNodeDetail> {
-  if (
-    !isMemoryConceptGraphEnabled(config) ||
-    !isMemoryV3Live(config) ||
-    !id ||
-    isCapabilitySlug(id)
-  ) {
+  if (!isMemoryConceptGraphEnabled(config) || !isMemoryV3Live(config) || !id) {
     return { found: false };
   }
+  // Seeded skill/CLI capabilities take precedence over any on-disk page at the
+  // same slug: the page index drops a colliding page and lets the synthetic win
+  // (v2/page-index.ts), so a `skills/foo` node built as the capability must not
+  // surface a stale disk page. renderCapabilityContent returns the rendered
+  // statement for a seeded capability, "" for an unseeded reserved-prefix slug
+  // (a real user page), and null for a normal concept slug.
+  if (isCapabilitySlug(id)) {
+    const content = renderCapabilityContent(id);
+    if (content) {
+      return { found: true, title: humanizeSlug(id), content };
+    }
+  }
+  // A real on-disk page: a concept, or a user page under a reserved prefix that
+  // isn't a seeded capability (kept in the index with a real mtime).
   const page = await readPage(getWorkspaceDir(), id).catch(() => null);
-  if (!page) {
-    return { found: false };
+  if (page) {
+    return { found: true, title: humanizeSlug(id), content: page.body };
   }
-  return { found: true, title: humanizeSlug(id), content: page.body };
+  return { found: false };
 }

package/src/plugins/defaults/memory/memory-retrospective-job.ts

@@ -77,6 +77,7 @@ import {
 import { resolveUserSlug } from "../../../prompts/persona-resolver.js";
 import type { SystemPromptPersonaOverride } from "../../../prompts/system-prompt.js";
 import { wakeAgentForOpportunity } from "../../../runtime/agent-wake.js";
+import { recordWatchdogEvent } from "../../../telemetry/watchdog-events-store.js";
 import { findMostRecentRetrospectiveFor } from "./find-most-recent-retrospective-for.js";
 import { getLogger } from "./logging.js";
 import { getRetrospectiveMessagesAfter } from "./memory-retrospective-accounting.js";
@@ -115,6 +116,9 @@ const FOLLOW_UP_JOB_TYPES: readonly MemoryJobType[] = [] as const;
  */
 export const SOURCE_PROCESSING_REQUEUE_DELAY_MS = 60_000;
 
+/** Watchdog check_name for the per-run retrospective outcome counter. */
+const MEMORY_RETROSPECTIVE_RUN_CHECK_NAME = "memory_retrospective_run";
+
 export type MemoryRetrospectiveOutcome =
   | { kind: "disabled" }
   | { kind: "no_new_messages" }
@@ -138,7 +142,42 @@ export async function memoryRetrospectiveJob(
     return { kind: "no_new_messages" };
   }
 
-  return runForkBasedRetrospective(sourceConversationId, config);
+  // Central health counter (admin analytics groups on the watchdog
+  // check_name): one event per run with its outcome kind. A run that
+  // throws records outcome "error" before the exception continues to the
+  // jobs worker's retry machinery, so a fleet-wide spike in
+  // `wake_failed`/`error` (e.g. a provider outage on the retrospective's
+  // resolved model) is visible without log access. The emitter itself
+  // never throws — the run's outcome must reach the jobs worker
+  // regardless.
+  const emitRunOutcome = (outcome: string, reason?: string): void => {
+    try {
+      recordWatchdogEvent({
+        checkName: MEMORY_RETROSPECTIVE_RUN_CHECK_NAME,
+        value: 1,
+        detail: {
+          outcome,
+          ...(reason ? { reason: reason.slice(0, 200) } : {}),
+        },
+      });
+    } catch {
+      // recordWatchdogEvent already no-ops on opt-out and a missing
+      // telemetry DB; anything past that is not worth surfacing here.
+    }
+  };
+
+  let outcome: MemoryRetrospectiveOutcome;
+  try {
+    outcome = await runForkBasedRetrospective(sourceConversationId, config);
+  } catch (err) {
+    emitRunOutcome("error", err instanceof Error ? err.message : String(err));
+    throw err;
+  }
+  emitRunOutcome(
+    outcome.kind,
+    outcome.kind === "wake_failed" ? outcome.reason : undefined,
+  );
+  return outcome;
 }
 
 // ---------------------------------------------------------------------------

package/src/plugins/defaults/memory/memory-retrospective-skill-card.ts

@@ -56,11 +56,15 @@ import {
   upsertSkillCardInsertJob,
 } from "../../../persistence/jobs-store.js";
 import { publishConversationMessagesChanged } from "../../../runtime/sync/resource-sync-events.js";
+import { recordWatchdogEvent } from "../../../telemetry/watchdog-events-store.js";
 import { getLogger } from "./logging.js";
 import { SKILL_CARD_MESSAGE_KIND } from "./memory-retrospective-constants.js";
 
 const log = getLogger("memory-retrospective-skill-card");
 
+/** Watchdog check_name for the per-card delivery counter. */
+const SKILL_CARD_DELIVERED_CHECK_NAME = "skill_card_delivered";
+
 /**
  * A skill authored by a retrospective run, as recorded by the scaffold
  * executor at creation time. All values are the executor's post-normalization
@@ -277,11 +281,19 @@ async function insertOrDeferSkillCard(
     return;
   }
   const surfaceId = `skill-card-${runConversationId}`;
+  // Copy matches the web card's row sentence (skill-created-card.tsx): the
+  // card reads as the assistant sharing what it picked up, not a technical
+  // "skill created" notice. The title covers renderers that only show the
+  // block title; the web card renders per-skill rows from `data.skills`.
+  const learnedSentence =
+    skills.length === 1
+      ? `I just learned how to do ${skills[0]!.name}`
+      : `I just learned how to do ${skills.length} new things`;
   const surfaceBlock = {
     type: "ui_surface",
     surfaceId,
     surfaceType: "skill_card",
-    title: "New skill learned",
+    title: learnedSentence,
     display: "inline",
     data: {
       skills: skills.map((s) => ({
@@ -298,7 +310,7 @@ async function insertOrDeferSkillCard(
   // rendered content blocks so the card is never double-rendered.
   const fallbackBlock = {
     type: "text",
-    text: `New skill learned: ${skills.map((s) => s.name).join(", ")}`,
+    text: `I just learned how to do ${skills.map((s) => s.name).join(", ")}`,
     _surfaceFallback: true,
   };
   const persisted = await addMessage(
@@ -334,6 +346,20 @@ async function insertOrDeferSkillCard(
     );
   }
   publishConversationMessagesChanged(sourceConversationId);
+  // Central delivery counter (admin analytics groups on the watchdog
+  // check_name): one event per delivered card, value = skills on it. The
+  // dedup early-return above keeps retried deliveries from double-counting.
+  // Never throws — the card is already inserted.
+  try {
+    recordWatchdogEvent({
+      checkName: SKILL_CARD_DELIVERED_CHECK_NAME,
+      value: skills.length,
+      detail: { skill_count: skills.length },
+    });
+  } catch {
+    // recordWatchdogEvent already no-ops on opt-out and a missing telemetry
+    // DB; anything past that is not worth surfacing here.
+  }
   log.info(
     {
       sourceConversationId,

package/src/plugins/mtime-cache.ts

@@ -72,6 +72,7 @@ import {
 import {
   clearSurfaceImportInflight,
   evictModule,
+  getFileSignature,
   getMtime,
   importWithTimeout,
   setSurfaceImportTimeout,
@@ -204,8 +205,13 @@ const disabledPluginDirs = new Set<string>();
  */
 let lastVersions: Record<string, PluginSourceVersion> = {};
 
-/** mtime of the sentinel document as of the last look; 0 = never seen. */
-let lastSentinelMtime = 0;
+/**
+ * Change signature (`mtimeMs:size:ino`) of the sentinel document as of the last
+ * look; `""` = never seen. A composite signature rather than mtime alone so a
+ * publish is detected even when the filesystem's mtime granularity can't move
+ * the timestamp between two rewrites (see {@link getFileSignature}).
+ */
+let lastSentinelSignature = "";
 
 /** In-flight reconcile — concurrent dispatches await it rather than racing. */
 let reconcileInFlight: Promise<void> | null = null;
@@ -254,11 +260,18 @@ export async function getUserHooksFor<TCtx = unknown>(
 
 /**
  * Dispatch-path gate: one stat of the source-versions sentinel. When its
- * mtime is unchanged since the last look (the overwhelmingly common case)
- * this returns immediately, and dispatch runs entirely on memory. When the
- * watcher published a change, the document is applied before the dispatch
+ * change signature is unchanged since the last look (the overwhelmingly common
+ * case) this returns immediately, and dispatch runs entirely on memory. When
+ * the watcher published a change, the document is applied before the dispatch
  * proceeds, so the turn that follows an edit already runs the new code.
  *
+ * The signature is `mtimeMs:size:ino`, not mtime alone: the sentinel is
+ * published via temp-file + atomic rename, which swaps in a fresh inode on
+ * every write, so a runtime install is picked up even on filesystems whose
+ * mtime granularity is too coarse to move the timestamp between two publishes
+ * (virtiofs / 9p / network mounts). With an mtime-only gate such a publish is
+ * invisible until the next daemon restart re-walks the plugins directory.
+ *
  * A missing or unreadable sentinel is degraded mode, not an error: the
  * boot-time state keeps serving, and live reload resumes when the monitor
  * publishes again.
@@ -273,14 +286,14 @@ async function maybeReconcileFromSentinel(): Promise<void> {
       await reconcileInFlight;
       continue;
     }
-    const mtime = getMtime(getSourceVersionsPath());
-    if (mtime === lastSentinelMtime) {
+    const signature = getFileSignature(getSourceVersionsPath());
+    if (signature === lastSentinelSignature) {
       return;
     }
-    // Claim the mtime before any async work, so a concurrent dispatch either
-    // finds the in-flight promise above or skips on the updated mtime.
-    lastSentinelMtime = mtime;
-    if (mtime === 0) {
+    // Claim the signature before any async work, so a concurrent dispatch
+    // either finds the in-flight promise above or skips on the updated value.
+    lastSentinelSignature = signature;
+    if (signature === "") {
       return;
     }
     const doc = readSourceVersions();
@@ -544,7 +557,7 @@ function seedVersionBaseline(): void {
     };
   }
   lastVersions = seeded;
-  lastSentinelMtime = getMtime(getSourceVersionsPath());
+  lastSentinelSignature = getFileSignature(getSourceVersionsPath());
 }
 
 // ─── Tool cache ──────────────────────────────────────────────────────────────
@@ -1031,7 +1044,7 @@ export function resetPluginCacheForTests(): void {
   activatedNames.clear();
   disabledPluginDirs.clear();
   lastVersions = {};
-  lastSentinelMtime = 0;
+  lastSentinelSignature = "";
   reconcileInFlight = null;
 }
 

package/src/plugins/plugin-tree-walk.ts

@@ -40,12 +40,39 @@ export const PRESERVED_ENTRIES = [
   ".disabled",
 ] as const;
 
+/**
+ * A generated app build directory: `apps/<app>/dist`. This is compiled output
+ * (the plugin source watcher builds each multi-file app's `src/` into its
+ * sibling `dist/`), never tracked source, so every fingerprint walk excludes
+ * it:
+ *
+ * - the **live-reload** change detector (`./source-fingerprint.ts`), so the
+ *   watcher's own compile does not read as a source change and re-trigger
+ *   itself in a loop, and
+ * - the **install/drift** fingerprint (`../cli/lib/plugin-fingerprint.ts`), so
+ *   generated output is not reported as drift/added against the pinned commit.
+ *
+ * Scoped to `apps/<app>/dist` specifically — a plugin's own top-level `dist/`
+ * (if it ships built code its hooks import) is still tracked.
+ */
+export function isGeneratedAppBuildDir(relDir: string): boolean {
+  const parts = relDir.split("/");
+  return parts.length === 3 && parts[0] === "apps" && parts[2] === "dist";
+}
+
 /** Options controlling which entries a {@link walkPluginTree} visits. */
 export interface PluginTreeWalkOptions {
   /** Top-level entry names to skip (e.g. {@link PRESERVED_ENTRIES}). */
   readonly excludeRootEntries?: Iterable<string>;
   /** Directory names skipped at any depth (e.g. `node_modules`). */
   readonly excludeDirsAnywhere?: ReadonlySet<string>;
+  /**
+   * Skip a directory (and its whole subtree) by its POSIX path relative to the
+   * walk root. Called for each directory before descending — use for
+   * path-scoped exclusions a bare directory name can't express (e.g. generated
+   * `apps/<app>/dist`, via {@link isGeneratedAppBuildDir}).
+   */
+  readonly excludeDir?: (relDir: string) => boolean;
   /** Skip entries whose name starts with `.`, at any depth. */
   readonly excludeDotEntries?: boolean;
   /**
@@ -96,6 +123,9 @@ export function walkPluginTree(
         if (options.excludeDirsAnywhere?.has(name) === true) {
           continue;
         }
+        if (options.excludeDir?.(rel) === true) {
+          continue;
+        }
         walk(rel);
       } else if (entry.isFile()) {
         visit(rel, join(absDir, name));

package/src/plugins/source-fingerprint.ts

@@ -18,7 +18,9 @@
  *
  * Exclusions: dot-entries anywhere (`.disabled`, `.git`, …), `node_modules`
  * anywhere (vendored deps change only through install flows, which recycle
- * the plugin directory), and — at the plugin root only — the runtime-owned
+ * the plugin directory), generated app build output ({@link
+ * isGeneratedAppBuildDir}, so the watcher's own compile does not re-trigger a
+ * pass), and — at the plugin root only — the runtime-owned
  * {@link PRESERVED_ENTRIES} (`data/`, `config.json`, `install-meta.json`),
  * none of which are importable source. Symlinked entries inside the tree are
  * neither watched nor followed (see {@link walkPluginTree}); a symlinked
@@ -30,7 +32,11 @@
 
 import { realpathSync, statSync } from "node:fs";
 
-import { PRESERVED_ENTRIES, walkPluginTree } from "./plugin-tree-walk.js";
+import {
+  isGeneratedAppBuildDir,
+  PRESERVED_ENTRIES,
+  walkPluginTree,
+} from "./plugin-tree-walk.js";
 
 /** Directory names skipped at any depth. */
 const EXCLUDED_DIRS_ANYWHERE = new Set(["node_modules"]);
@@ -78,6 +84,7 @@ export function snapshotPluginSource(pluginDir: string): SourceSnapshot {
     {
       excludeRootEntries: PRESERVED_ENTRIES,
       excludeDirsAnywhere: EXCLUDED_DIRS_ANYWHERE,
+      excludeDir: isGeneratedAppBuildDir,
       excludeDotEntries: true,
       bestEffort: true,
     },

package/src/plugins/surface-import.ts

@@ -50,6 +50,34 @@ export function getMtime(filePath: string): number {
   }
 }
 
+/**
+ * Composite change signature for a file — `mtimeMs:size:ino` — or `""` when the
+ * file is absent or can't be stat'd.
+ *
+ * Unlike {@link getMtime}, this detects a rewrite even when the filesystem's
+ * mtime resolution is too coarse to move the timestamp (or two rewrites land in
+ * the same timestamp granule). The source-versions sentinel is published via a
+ * temp-file + atomic rename, which swaps in a fresh inode on every write, so
+ * `ino` changes even when `mtimeMs` does not — and `size` shifts too whenever
+ * the plugin set does. Gating the reconcile on this signature (rather than
+ * mtime alone) is what lets a plugin installed at runtime go live on
+ * filesystems whose mtime granularity is coarse (virtiofs / 9p / network mounts
+ * — the same mounts the plugin-source watcher polls precisely because their
+ * timestamps are unreliable) instead of only after the next daemon restart.
+ *
+ * Change detection only — the exact numbers are never interpreted, so inode
+ * values above 2^53 losing float precision cannot cause a missed update: `mtime`
+ * and `size` still move on a real publish.
+ */
+export function getFileSignature(filePath: string): string {
+  try {
+    const st = statSync(filePath);
+    return `${st.mtimeMs}:${st.size}:${st.ino}`;
+  } catch {
+    return "";
+  }
+}
+
 /**
  * Evict `filePath` from the runtime module registry so the next dynamic
  * `import()` of that path re-evaluates the file from disk.

package/src/providers/speech-to-text/__tests__/vellum-managed-realtime.test.ts

@@ -204,7 +204,7 @@ describe("VellumManagedRealtimeTranscriber", () => {
       expect.objectContaining({
         type: "error",
         category: "auth",
-        message: expect.stringContaining("platform connect"),
+        message: expect.stringContaining("VELAY_BASE_URL"),
       }),
     );
   });

package/src/providers/speech-to-text/__tests__/vellum-speech-relay-connection.test.ts

@@ -54,7 +54,10 @@ describe("resolveSpeechRelayConnection", () => {
 
 describe("mapVelayError", () => {
   test("maps the relay contract's codes onto categories", () => {
-    expect(mapVelayError({ code: "invalid_key" }).category).toBe("auth");
+    expect(mapVelayError({ code: "invalid_key" })).toMatchObject({
+      category: "auth",
+      message: expect.stringContaining("VELAY_BASE_URL"),
+    });
     expect(
       mapVelayError({ code: "missing_platform_connection" }),
     ).toMatchObject({

package/src/providers/speech-to-text/vellum-speech-relay-connection.ts

@@ -99,6 +99,11 @@ export function mapVelayError(error: VelayErrorInfo): {
 } {
   switch (error.code) {
     case "invalid_key":
+      return {
+        category: "auth",
+        message:
+          "The Vellum speech relay rejected this assistant's API key — the assistant's platform environment may not match the relay it is dialing (set VELAY_BASE_URL on the gateway to the matching environment, e.g. https://velay-staging.vellum.ai for staging).",
+      };
     case "missing_platform_connection":
       return {
         category: "auth",