@vellumai/assistant 0.8.3 → 0.8.5

package/src/plugins/defaults/injectors.ts

@@ -20,6 +20,7 @@
  * | `memory-v2-static`       | 38    | after-memory-prefix     |
  * | `now-md`                 | 40    | after-memory-prefix     |
  * | `active-documents`       | 45    | prepend-user-tail       |
+ * | `document-comments`      | 46    | prepend-user-tail       |
  * | `subagent-status`        | 50    | append-user-tail        |
  * | `slack-messages`         | 60    | replace-run-messages    |
  * | `thread-focus`           | 70    | append-user-tail        |
@@ -51,6 +52,7 @@ import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-fl
 import { getConfig } from "../../config/loader.js";
 import { getInContextPkbPaths } from "../../daemon/pkb-context-tracker.js";
 import { buildPkbReminder } from "../../daemon/pkb-reminder-builder.js";
+import { listComments } from "../../documents/document-comments-store.js";
 import { searchPkbFiles } from "../../memory/pkb/pkb-search.js";
 import { getLogger } from "../../util/logger.js";
 import { registerPlugin } from "../registry.js";
@@ -94,6 +96,7 @@ export const DEFAULT_INJECTOR_ORDER = {
   memoryV2Static: 38,
   nowMd: 40,
   activeDocuments: 45,
+  documentComments: 46,
   subagentStatus: 50,
   slackMessages: 60,
   threadFocus: 70,
@@ -133,12 +136,11 @@ const diskPressureWarningInjector: Injector = {
 };
 
 /**
- * v2 read-side cutover guard. The `pkb-context` injector silences itself
- * under v2 because the `<knowledge_base>` block surfaces PKB content the v2
- * activation block already covers. The `pkb-reminder` injector still fires
- * (its body is generic recall/remember guidance) but skips the hybrid-search
- * hints — those name PKB paths v2 is moving away from. NOW.md is workspace
- * state independent of PKB and fires unchanged.
+ * v2 read-side cutover guard. Under v2 both `pkb-context` and `pkb-reminder`
+ * silence themselves entirely — the `<knowledge_base>` content and the
+ * generic recall/remember nudge are both supplanted by the v2 static
+ * `<memory>` block. NOW.md is workspace state independent of PKB and fires
+ * unchanged.
  */
 function isPkbInjectionSilencedByV2(): boolean {
   return getConfig().memory.v2.enabled;
@@ -287,9 +289,8 @@ const pkbReminderInjector: Injector = {
     const mode = inputs.mode ?? "full";
     if (mode !== "full") return null;
     if (!inputs.pkbActive) return null;
-    const reminder = isPkbInjectionSilencedByV2()
-      ? buildPkbReminder([])
-      : await buildPkbReminderWithHints(inputs);
+    if (isPkbInjectionSilencedByV2()) return null;
+    const reminder = await buildPkbReminderWithHints(inputs);
     return {
       id: "pkb-reminder",
       text: reminder,
@@ -386,17 +387,20 @@ async function buildPkbReminderWithHints(
  * `memory-v2-static` injector — order 38, after-memory-prefix.
  *
  * Injects the v2 static memory block (essentials/threads/recent/buffer
- * concatenated under markdown headings) wrapped in `<memory>...</memory>`
+ * concatenated under markdown headings) wrapped in `<info>...</info>`
  * onto the user message. The agent loop only forwards `memoryV2Static` on
  * full-mode turns (first turn / post-compaction), mirroring the PKB
  * auto-inject cadence — subsequent turns get `null` and the prior block
  * stays cached on its original user message.
  *
- * Sits between `pkb-reminder` (35) and `now-md` (40) so the rendered order
- * after the memory prefix is `[pkb-reminder, pkb-context, memory-v2-static,
- * now-md, ...user text]` when every PKB injector also fires (transitional
- * state). Once PKB is fully retired under v2 this is the only block
- * adjacent to the memory prefix.
+ * Sits between `pkb-reminder` (35) and `now-md` (40). Because every
+ * after-memory-prefix splice lands at the memory-prefix boundary in
+ * ascending `order`, higher-order blocks end up closer to the memory
+ * prefix. The rendered layout is therefore `[<memory>dynamic</memory>,
+ * <info>memory-v2-static</info>, <NOW.md>, <system_reminder>,
+ * <knowledge_base>, ...user text]` when every PKB injector also fires.
+ * `countMemoryPrefixBlocks` treats the `<info>` static block as part of
+ * the memory prefix so `now-md` (40) splices after it.
  *
  * Gating:
  *  - `mode === "full"`.
@@ -419,14 +423,18 @@ const memoryV2StaticInjector: Injector = {
   },
 };
 
+const INFO_CLOSE_TAG_RE = /<\/info\s*>/gi;
+
 /**
- * Wrap the static memory content in `<memory>...</memory>`. Escapes any
- * closing `</memory>` inside the content so authored memory files cannot
- * accidentally break out of the wrapper.
+ * Wrap the static memory content in `<info>...</info>`. Escapes any
+ * closing `</info>` inside the content so authored memory files cannot
+ * accidentally break out of the wrapper. Distinct from the dynamic
+ * activation block (which uses `<memory>...</memory>`) so downstream
+ * logic can address the two differently.
  */
 function buildMemoryV2StaticBlock(content: string): string {
-  const escaped = content.replace(/<\/memory\s*>/gi, "&lt;/memory&gt;");
-  return `<memory>\n${escaped}\n</memory>`;
+  const escaped = content.replace(INFO_CLOSE_TAG_RE, "&lt;/info&gt;");
+  return `<info>\n${escaped}\n</info>`;
 }
 
 /**
@@ -491,6 +499,77 @@ const activeDocumentsInjector: Injector = {
   },
 };
 
+/** Maximum open comments surfaced per document to limit context bloat. */
+const DOCUMENT_COMMENTS_CAP = 10;
+
+/**
+ * Escape closing `</document_comments>` inside user-controlled strings so
+ * they cannot break out of the XML wrapper — same pattern as
+ * {@link buildPkbContextBlock} and {@link buildMemoryV2StaticBlock}.
+ */
+function escapeDocCommentTag(s: string): string {
+  return s.replace(/<\/document_comments\s*>/gi, "&lt;/document_comments&gt;");
+}
+
+/**
+ * `document-comments` injector — order 46, prepend-user-tail.
+ *
+ * Surfaces open top-level comments on active documents so the assistant
+ * knows what feedback to address. For each active document, queries the
+ * comment store for open top-level comments (capped at
+ * {@link DOCUMENT_COMMENTS_CAP} most recent per document). Inline comments
+ * include the quoted anchor text; doc-level comments are labelled as such.
+ *
+ * Gating:
+ *  - `mode === "full"`.
+ *  - `activeDocuments` has at least one entry.
+ *  - At least one document has open comments (returns null otherwise).
+ */
+const documentCommentsInjector: Injector = {
+  name: "document-comments",
+  order: DEFAULT_INJECTOR_ORDER.documentComments,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    const inputs = readInjectionInputs(ctx);
+    const mode = inputs.mode ?? "full";
+    if (mode !== "full") return null;
+    const docs = inputs.activeDocuments;
+    if (!docs || docs.length === 0) return null;
+
+    const sections: string[] = [];
+    for (const doc of docs) {
+      const comments = listComments(doc.surfaceId, {
+        status: "open",
+        topLevelOnly: true,
+      }).slice(-DOCUMENT_COMMENTS_CAP);
+      if (comments.length === 0) continue;
+
+      const lines = comments.map((c) => {
+        const anchor =
+          c.anchorText != null ? escapeDocCommentTag(c.anchorText) : null;
+        const label =
+          anchor != null ? `inline, anchored to "${anchor}"` : "doc-level";
+        return `- Comment #${c.id} (${label}): "${escapeDocCommentTag(c.content)}"`;
+      });
+      sections.push(
+        `Document: "${escapeDocCommentTag(doc.title)}" (surface_id: "${doc.surfaceId}")\n${lines.join("\n")}`,
+      );
+    }
+
+    if (sections.length === 0) return null;
+
+    const text = `<document_comments>
+Open comments on your documents. Address these by editing the document, then use comment_resolve to mark each resolved.
+
+${sections.join("\n\n")}
+</document_comments>`;
+    return {
+      id: "document-comments",
+      text,
+      placement: "prepend-user-tail",
+    };
+  },
+};
+
 /**
  * `subagent-status` injector — order 50, append-user-tail.
  *
@@ -626,6 +705,7 @@ export const defaultInjectorsPlugin: Plugin = {
     memoryV2StaticInjector,
     nowMdInjector,
     activeDocumentsInjector,
+    documentCommentsInjector,
     subagentStatusInjector,
     slackMessagesInjector,
     threadFocusInjector,

package/src/plugins/external-plugin-loader.ts

@@ -49,12 +49,8 @@ import semver from "semver";
 import { z } from "zod";
 
 import assistantPkg from "../../package.json" with { type: "json" };
-import type {
-  LoadedPluginTool,
-  PluginTool,
-  RiskLevel,
-  ToolExecutionResult,
-} from "../tools/types.js";
+import { finalizeTool } from "../tools/tool-defaults.js";
+import type { LoadedTool, ToolDefinition } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
 import { registerPlugin } from "./registry.js";
 import type {
@@ -62,7 +58,6 @@ import type {
   PluginHookFn,
   PluginHooks,
   PluginManifest,
-  PluginToolRegistration,
 } from "./types.js";
 
 const PLUGIN_API_PEER_DEP = "@vellumai/plugin-api";
@@ -122,64 +117,6 @@ function deriveToolName(toolFileBaseName: string): string {
   return toToolNameSegment(toolFileBaseName);
 }
 
-/**
- * Defaults applied by {@link applyPluginToolDefaults} when a plugin tool
- * omits one of the normally-required fields. Exported as a constant so
- * tests and callers can reference the same source of truth.
- *
- * The default `execute` returns an error result so the model sees a clear
- * "this tool isn't wired up" signal at call time. The plugin still loads
- * cleanly — broken individual tools must never block daemon boot.
- */
-export const PLUGIN_TOOL_DEFAULTS = Object.freeze({
-  description: "",
-  defaultRiskLevel: "medium" as RiskLevel,
-  input_schema: Object.freeze({
-    type: "object",
-    properties: {},
-    additionalProperties: false,
-  }) as object,
-});
-
-/**
- * Fill the four normally-required {@link PluginTool} fields with documented
- * defaults when the author omitted them. Returns a {@link LoadedPluginTool}
- * that is safe to register.
- */
-function applyPluginToolDefaults(
-  tool: PluginTool,
-  name: string,
-): LoadedPluginTool {
-  const description =
-    typeof tool.description === "string"
-      ? tool.description
-      : PLUGIN_TOOL_DEFAULTS.description;
-  const defaultRiskLevel =
-    typeof tool.defaultRiskLevel === "string"
-      ? tool.defaultRiskLevel
-      : PLUGIN_TOOL_DEFAULTS.defaultRiskLevel;
-  const input_schema =
-    tool.input_schema !== null &&
-    typeof tool.input_schema === "object"
-      ? tool.input_schema
-      : PLUGIN_TOOL_DEFAULTS.input_schema;
-  const execute =
-    typeof tool.execute === "function"
-      ? tool.execute
-      : async (): Promise<ToolExecutionResult> => ({
-          content: `plugin tool ${name} has no execute implementation`,
-          isError: true,
-        });
-  return {
-    ...tool,
-    name,
-    description,
-    defaultRiskLevel,
-    input_schema,
-    execute,
-  };
-}
-
 /**
  * Dynamic-import `absolutePath` and return its default export. Throws when
  * the module has no default export — callers attribute the error.
@@ -339,17 +276,17 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
   const hooks = await loadHooks(pluginDir, name);
   if (hooks !== undefined) plugin.hooks = hooks;
 
-  const tools: PluginToolRegistration[] = [];
+  const tools: LoadedTool[] = [];
   for (const { name: toolName, path: toolPath } of listSurfaceDir(
     join(pluginDir, "tools"),
   )) {
-    const tool = await importDefault<PluginTool>(toolPath);
+    const tool = await importDefault<ToolDefinition>(toolPath);
     if (tool === null || typeof tool !== "object") {
       throw new Error(
         `external plugin ${name}: ${toolPath} default export must be an object`,
       );
     }
-    tools.push(applyPluginToolDefaults(tool, deriveToolName(toolName)));
+    tools.push(finalizeTool(tool, deriveToolName(toolName)));
   }
   if (tools.length > 0) plugin.tools = tools;
 

package/src/plugins/types.ts

@@ -43,7 +43,7 @@ import type {
 } from "../providers/types.js";
 import type { SkillRoute } from "../runtime/skill-route-registry.js";
 import type {
-  LoadedPluginTool,
+  LoadedTool,
   ToolContext,
   ToolExecutionResult,
 } from "../tools/types.js";
@@ -1007,19 +1007,6 @@ export interface Injector {
 // `PluginSkillRegistration` shape below so plugins can declare
 // catalog-discoverable skills today.
 
-/**
- * Tool registration contributed by a plugin. Uses the narrow
- * {@link LoadedPluginTool} shape. External plugin authors declare the
- * nameless `PluginTool` file shape; the loader derives `name` from the
- * `tools/<name>.ts` basename before storing it on `plugin.tools`. Authors
- * also leave category / ownership metadata to the bootstrap, which stamps
- * `category: "plugin"`, `origin: "plugin"`, and
- * `ownerPluginId: <plugin.name>` before handing the batch to
- * `registerPluginTools`. The registration boundary synthesizes
- * `getDefinition()` from `{name, description, input_schema}` so the canonical
- * {@link Tool} interface used by the internal registry stays unchanged.
- */
-export type PluginToolRegistration = LoadedPluginTool;
 /**
  * HTTP route registration contributed by a plugin. Plugins express routes as
  * {@link SkillRoute} values — the same shape the skill-route registry
@@ -1120,8 +1107,16 @@ export interface Plugin {
   manifest: PluginManifest;
   /** Lifecycle hooks (init, shutdown). See {@link PluginHooks}. */
   hooks?: PluginHooks;
-  /** Tool registrations visible to the model. */
-  tools?: PluginToolRegistration[];
+  /**
+   * Tool registrations visible to the model. External plugin authors
+   * declare the nameless `ToolDefinition` file shape (from
+   * `@vellumai/plugin-api`); the loader derives `name` from the
+   * `tools/<name>.ts` basename and runs the definition through
+   * `finalizeTool` to fill omitted required fields, producing the
+   * `LoadedTool` values stored here. Category / ownership metadata is
+   * stamped by `registerPluginTools` at registration time.
+   */
+  tools?: LoadedTool[];
   /** HTTP route registrations served by the assistant. */
   routes?: PluginRouteRegistration[];
   /** Skill registrations loaded at startup. */

package/src/proactive-artifact/aux-message-injector.ts

@@ -71,10 +71,23 @@ export async function injectAuxAssistantMessage(params: {
     });
   }
 
-  params.broadcastMessage({
-    type: "conversation_list_invalidated",
-    reason: "reordered",
-  });
+  // The injected aux message bumps `lastMessageAt`, which can move the
+  // row in the paginated sidebar window — that's a shape change. macOS
+  // refreshes its full list on `conversation_list_invalidated`; web
+  // refreshes via the paired `sync_changed` `conversationsList` tag.
+  //
+  // TODO(electron-cutover): drop the `conversation_list_invalidated`
+  // emission once macOS migrates to the Electron client and consumes
+  // `sync_changed` directly. See `runtime/sync/resource-sync-events.ts`
+  // for the symmetric helper used by route handlers.
+  params.broadcastMessage(
+    {
+      type: "conversation_list_invalidated",
+      reason: "reordered",
+    },
+    undefined,
+    { targetInterfaceId: "macos" },
+  );
   params.broadcastMessage({
     type: "sync_changed",
     tags: [

package/src/prompts/__tests__/system-prompt.test.ts

@@ -6,7 +6,8 @@
  * user-message injection that replaced it.
  */
 
-import { mkdirSync } from "node:fs";
+import { copyFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 const TEST_DIR = process.env.VELLUM_WORKSPACE_DIR!;
@@ -57,7 +58,8 @@ mock.module("../../config/loader.js", () => ({
   setNestedValue: () => {},
 }));
 
-const { buildSystemPrompt } = await import("../system-prompt.js");
+const { buildSystemPrompt, maybeReseedBootstrapForCohort } =
+  await import("../system-prompt.js");
 
 describe("buildSystemPrompt — tool routing guidance", () => {
   beforeEach(() => {
@@ -70,3 +72,45 @@ describe("buildSystemPrompt — tool routing guidance", () => {
     expect(result).not.toContain("ask_question");
   });
 });
+
+describe("maybeReseedBootstrapForCohort — content-automation template", () => {
+  const templatesDir = join(import.meta.dirname!, "..", "templates");
+
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    // Seed the workspace with the generic BOOTSTRAP.md so the cohort
+    // reseed detects it as an unmodified template and overwrites it.
+    copyFileSync(
+      join(templatesDir, "BOOTSTRAP.md"),
+      join(TEST_DIR, "BOOTSTRAP.md"),
+    );
+  });
+
+  function reseedAndRead(): string {
+    maybeReseedBootstrapForCohort("content-automation");
+    return readFileSync(join(TEST_DIR, "BOOTSTRAP.md"), "utf-8");
+  }
+
+  test("loads the geo-writing skill on first turn", () => {
+    const content = reseedAndRead();
+    expect(content).toContain("geo-writing");
+  });
+
+  test("uses skill-first onboarding approach", () => {
+    const content = reseedAndRead();
+    expect(content).toContain("Skill-First Onboarding");
+    expect(content).toContain("The skill is the onboarding");
+  });
+
+  test("includes comment-driven edit loop", () => {
+    const content = reseedAndRead();
+    expect(content).toContain("comment-driven");
+    expect(content).toContain("comment_resolve");
+    expect(content).toContain("document_update");
+  });
+
+  test("references VOICE.md for voice capture", () => {
+    const content = reseedAndRead();
+    expect(content).toContain("VOICE.md");
+  });
+});

package/src/prompts/__tests__/task-progress-hint-section.test.ts

@@ -54,8 +54,9 @@ mock.module("../../config/loader.js", () => ({
   setNestedValue: () => {},
 }));
 
-const { buildSystemPrompt, ensurePromptFiles, SYSTEM_PROMPT_CACHE_BOUNDARY } =
-  await import("../system-prompt.js");
+const { buildSystemPrompt, ensurePromptFiles } = await import(
+  "../system-prompt.js"
+);
 
 describe("task_progress hint in parallel-tool-calls section", () => {
   beforeEach(() => {
@@ -85,11 +86,4 @@ describe("task_progress hint in parallel-tool-calls section", () => {
     expect(withExcludePrefix).toContain("task_progress");
   });
 
-  test("hint lives in the static (cached) block before SYSTEM_PROMPT_CACHE_BOUNDARY", () => {
-    const result = buildSystemPrompt();
-    const boundaryIdx = result.indexOf(SYSTEM_PROMPT_CACHE_BOUNDARY);
-    expect(boundaryIdx).toBeGreaterThan(-1);
-    const staticBlock = result.slice(0, boundaryIdx);
-    expect(staticBlock).toContain("task_progress");
-  });
 });

package/src/prompts/normalize-onboarding.ts

@@ -19,6 +19,20 @@ export const TOOL_DISPLAY_NAMES: Record<string, string> = {
   "apple-notes": "Apple Notes",
 };
 
+/**
+ * Map of known prior-assistant IDs (from the client onboarding UI) to display names.
+ * Unknown IDs pass through with first-letter capitalization via `normalizePriorAssistants`.
+ */
+export const PRIOR_ASSISTANT_DISPLAY_NAMES: Record<string, string> = {
+  chatgpt: "ChatGPT",
+  claude: "Claude",
+  openclaw: "OpenClaw",
+  hermes: "Hermes",
+  manus: "Manus",
+  gemini: "Gemini",
+  copilot: "Copilot",
+};
+
 /**
  * Map of known task IDs to plain-language labels describing what the assistant
  * does for each task category.
@@ -56,14 +70,28 @@ export function normalizeTasks(tasks: string[]): string[] {
   return tasks.map((id) => TASK_DISPLAY_LABELS[id] ?? id);
 }
 
+/**
+ * Maps each prior-assistant ID through `PRIOR_ASSISTANT_DISPLAY_NAMES`,
+ * falling back to first-letter capitalization for unknown IDs.
+ */
+export function normalizePriorAssistants(assistants: string[]): string[] {
+  return assistants.map(
+    (id) => PRIOR_ASSISTANT_DISPLAY_NAMES[id] ?? capitalizeFirst(id),
+  );
+}
+
 export interface NormalizedOnboarding {
   preferredName?: string;
   commonWork: string[];
   dailyTools: string[];
   tone?: string;
   assistantName?: string;
+  priorAssistants?: string[];
   googleConnected?: boolean;
   googleServices?: string[];
+  cohort?: string;
+  websiteUrl?: string;
+  contentSourceUrl?: string;
 }
 
 const SCOPE_SERVICE_MAP: Record<string, string> = {
@@ -103,5 +131,17 @@ export function normalizeOnboardingContext(
     googleServices: ctx.googleConnected
       ? deriveGoogleServices(ctx.googleScopes)
       : undefined,
+    priorAssistants: ctx.priorAssistants?.length
+      ? normalizePriorAssistants(ctx.priorAssistants)
+      : undefined,
+    cohort: ctx.cohort,
+    websiteUrl:
+      typeof ctx.websiteUrl === "string"
+        ? ctx.websiteUrl.trim().replace(/[\r\n\t]/g, "") || undefined
+        : undefined,
+    contentSourceUrl:
+      typeof ctx.contentSourceUrl === "string"
+        ? ctx.contentSourceUrl.trim().replace(/[\r\n\t]/g, "") || undefined
+        : undefined,
   };
 }

package/src/prompts/persona-resolver.ts

@@ -77,31 +77,46 @@ function resolveUserFilename(
 ): string | null {
   let filename: string | null = null;
 
-  if (trustContext === undefined) {
-    // Desktop / native (no gateway) — resolve via guardian contact,
-    // preferring the vellum-channel guardian when multiple exist.
-    const vellumGuardian = findGuardianForChannel("vellum");
-    const guardian = vellumGuardian ?? listGuardianChannels();
-    if (guardian) {
-      filename = guardian.contact.userFile ?? "guardian.md";
-    }
-  } else if (trustContext.requesterExternalUserId) {
-    // Channel-routed request — look up contact by channel identity
-    const contactWithChannels = findContactByChannelExternalId(
-      trustContext.sourceChannel,
-      trustContext.requesterExternalUserId,
-    );
-    if (contactWithChannels) {
-      filename = contactWithChannels.userFile ?? null;
-    } else if (trustContext.trustClass === "guardian") {
-      // Managed desktop: the JWT principal ID used as requesterExternalUserId
-      // may differ from the contact channel's external_user_id (they are
-      // separate identity concepts). Fall back to the channel-type guardian.
-      const guardian = findGuardianForChannel(trustContext.sourceChannel);
+  try {
+    if (trustContext === undefined) {
+      // Desktop / native (no gateway) — resolve via guardian contact,
+      // preferring the vellum-channel guardian when multiple exist.
+      const vellumGuardian = findGuardianForChannel("vellum");
+      const guardian = vellumGuardian ?? listGuardianChannels();
       if (guardian) {
         filename = guardian.contact.userFile ?? "guardian.md";
       }
+    } else if (trustContext.requesterExternalUserId) {
+      // Channel-routed request — look up contact by channel identity
+      const contactWithChannels = findContactByChannelExternalId(
+        trustContext.sourceChannel,
+        trustContext.requesterExternalUserId,
+      );
+      if (contactWithChannels) {
+        filename = contactWithChannels.userFile ?? null;
+      } else if (trustContext.trustClass === "guardian") {
+        // Managed desktop: the JWT principal ID used as requesterExternalUserId
+        // may differ from the contact channel's external_user_id (they are
+        // separate identity concepts). Fall back to the channel-type guardian.
+        const guardian = findGuardianForChannel(trustContext.sourceChannel);
+        if (guardian) {
+          filename = guardian.contact.userFile ?? "guardian.md";
+        }
+      }
     }
+  } catch (err) {
+    // Contacts table may be absent — happens during early bootstrap
+    // before migrations run, in CLI smoke commands that don't touch
+    // the DB, and in tests that build the system prompt without first
+    // initializing a schema. Treat the same as "no guardian found"
+    // so callers fall back to `users/default.md`. Mirrors the same
+    // try/catch pattern used by `renderConnectedServices()` around
+    // `listConnections()`.
+    log.debug(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Contacts lookup failed during persona resolution; treating as no guardian",
+    );
+    return null;
   }
 
   // Validate basename to prevent path traversal