@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

package/src/__tests__/oauth-provider-serializer.test.ts

@@ -291,9 +291,26 @@ describe("serializeProviderSummary", () => {
       supports_managed_mode: true,
       managed_service_is_paid: false,
       feature_flag: null,
+      acts_as: "user",
     });
   });
 
+  test("names which sense of connected a provider represents", () => {
+    // The provider key does not say, and the naming actively misleads:
+    // `slack` is the user integration while its bot is `slack_channel`, but
+    // `telegram` is itself the bot. A caller asking "is X connected?" needs
+    // this to answer which X it found.
+    const sense = (provider: string) =>
+      serializeProviderSummary(makeRow({ provider }))!.acts_as;
+
+    expect(sense("slack")).toBe("user");
+    expect(sense("slack_channel")).toBe("assistant");
+    expect(sense("discord")).toBe("user");
+    expect(sense("discord_channel")).toBe("assistant");
+    expect(sense("telegram")).toBe("assistant");
+    expect(sense("google")).toBe("user");
+  });
+
   test("nullifies missing optional fields", () => {
     const row = makeRow({
       displayLabel: null,

package/src/__tests__/oauth-providers-routes.test.ts

@@ -178,6 +178,7 @@ describe("GET /v1/oauth/providers", () => {
       "supports_managed_mode",
       "managed_service_is_paid",
       "feature_flag",
+      "acts_as",
     ];
 
     for (const provider of providers) {

package/src/__tests__/openai-responses-prompt-cache.test.ts

@@ -238,16 +238,19 @@ describe("OpenAIResponsesProvider explicit prompt caching (GPT-5.6+)", () => {
     expect(breakpointedItemIndexes()).toEqual([0, 2]);
   });
 
-  test("volatile single-message first turn: no markers (nothing stable to anchor)", async () => {
+  test("volatile single-message first turn: the sole item is still marked", async () => {
     const provider = makeProvider("gpt-5.6-sol");
     await provider.sendMessage([userMsg("hi")], {
       config: { mutableLatestUserMessage: true, promptCacheKey: "conv-1" },
     });
 
+    // A volatile message is fixed within its own turn, so marking it prepays
+    // one write that the turn's tool-loop iterations read back, covering the
+    // instructions and tools that precede it in the cached prefix.
     expect(lastStreamParams?.prompt_cache_options).toEqual({
       mode: "explicit",
     });
-    expect(breakpointedItemIndexes()).toEqual([]);
+    expect(breakpointedItemIndexes()).toEqual([0]);
   });
 
   test("tool loop: single fixed anchor on the turn-start user item, none on function_call_output", async () => {

package/src/__tests__/path-policy.test.ts

@@ -15,6 +15,7 @@ import {
   resolveRealPath,
   sandboxPolicy,
   sandboxPolicyWithHostFallback,
+  sandboxReadPolicy,
 } from "../tools/shared/filesystem/path-policy.js";
 import { getDotEnvPath } from "../util/platform.js";
 
@@ -506,6 +507,162 @@ describe("sandboxPolicyWithHostFallback", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Sandbox read policy
+// ---------------------------------------------------------------------------
+
+describe("sandboxReadPolicy", () => {
+  afterEach(() => {
+    delete process.env.IS_CONTAINERIZED;
+    delete process.env.GATEWAY_SECURITY_DIR;
+    delete process.env.CREDENTIAL_SECURITY_DIR;
+  });
+
+  test("matches sandboxPolicy for in-bounds paths", () => {
+    const boundary = makeTempDir();
+    mkdirSync(join(boundary, "sub"));
+
+    const result = sandboxReadPolicy("sub/file.txt", boundary);
+    expect(result).toEqual(sandboxPolicy("sub/file.txt", boundary));
+    expect(result.ok).toBe(true);
+  });
+
+  test("reads outside the boundary when containerized", () => {
+    const boundary = makeTempDir();
+    const installTree = makeTempDir();
+    const target = join(installTree, "SKILL.md");
+    writeFileSync(target, "# skill");
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(target, boundary);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.resolved).toBe(target);
+    }
+  });
+
+  test("follows an in-boundary symlink that points outside", () => {
+    const boundary = makeTempDir();
+    const outside = makeTempDir();
+    const target = join(outside, "reference.md");
+    writeFileSync(target, "reference body");
+    symlinkSync(target, join(boundary, "link.md"));
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(join(boundary, "link.md"), boundary);
+    expect(result.ok).toBe(true);
+  });
+
+  test("denies the gateway security dir when containerized", () => {
+    const boundary = makeTempDir();
+    const securityDir = makeTempDir();
+    writeFileSync(join(securityDir, "trust.json"), "{}");
+    process.env.GATEWAY_SECURITY_DIR = securityDir;
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(join(securityDir, "trust.json"), boundary);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("denied");
+    }
+  });
+
+  test("denies a symlink that resolves into the credential security dir", () => {
+    const boundary = makeTempDir();
+    const securityDir = makeTempDir();
+    writeFileSync(join(securityDir, "keys.enc"), "cipher");
+    symlinkSync(join(securityDir, "keys.enc"), join(boundary, "innocent.txt"));
+    process.env.CREDENTIAL_SECURITY_DIR = securityDir;
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(join(boundary, "innocent.txt"), boundary);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("denied");
+    }
+  });
+
+  test("denies a denylisted basename outside the boundary", () => {
+    const boundary = makeTempDir();
+    const outside = makeTempDir();
+    writeFileSync(join(outside, "backup.key"), "key");
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(join(outside, "backup.key"), boundary);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("denied");
+    }
+  });
+
+  test("fails closed to the hard boundary when a security-dir override is relative", () => {
+    const boundary = makeTempDir();
+    const outside = makeTempDir();
+    writeFileSync(join(outside, "file.txt"), "x");
+    // Unmirrorable deny set: the real security dir could be anywhere, so the
+    // read allowance must not widen past the boundary.
+    process.env.GATEWAY_SECURITY_DIR = "relative/security-dir";
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(join(outside, "file.txt"), boundary);
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("out_of_bounds");
+    }
+  });
+
+  // The daemon's own environment carries the actor token signing key, the CES
+  // service token, the guardian bootstrap secret, and forwarded provider API
+  // keys, so no policy may serve a process environment block.
+  test.each([
+    "/proc/self/environ",
+    "/proc/thread-self/environ",
+    "/proc/1/environ",
+    "/proc/4242/environ",
+  ])("denies %s", (path) => {
+    const boundary = makeTempDir();
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(path, boundary, { mustExist: false });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("denied");
+    }
+  });
+
+  test("denies a process environ path reached through a symlink", () => {
+    const boundary = makeTempDir();
+    symlinkSync("/proc/self/environ", join(boundary, "innocent.txt"));
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy(join(boundary, "innocent.txt"), boundary, {
+      mustExist: false,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe("denied");
+    }
+  });
+
+  test("still allows other /proc entries", () => {
+    const boundary = makeTempDir();
+    process.env.IS_CONTAINERIZED = "true";
+
+    const result = sandboxReadPolicy("/proc/self/status", boundary, {
+      mustExist: false,
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  test("does not deny an unrelated file named environ", () => {
+    const boundary = makeTempDir();
+    writeFileSync(join(boundary, "environ"), "notes");
+
+    const result = sandboxReadPolicy("environ", boundary);
+    expect(result.ok).toBe(true);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Host policy
 // ---------------------------------------------------------------------------
@@ -575,7 +732,13 @@ describe("resolveRealPath", () => {
   });
 
   test("falls back to the lexical path when nothing on it exists", () => {
-    const phantom = join(tmpdir(), "definitely-not-here-12345", "nope.txt");
+    // realpath the temp root so a symlinked prefix (macOS /var -> /private/var)
+    // is not mistaken for the resolution under test.
+    const phantom = join(
+      realpathSync(tmpdir()),
+      "definitely-not-here-12345",
+      "nope.txt",
+    );
     expect(resolveRealPath(phantom)).toBe(phantom);
   });
 });

package/src/__tests__/persist-media-references.test.ts

@@ -49,7 +49,7 @@ describe("referenceMediaBlocksForPersist", () => {
       },
     ];
 
-    const referenced = referenceMediaBlocksForPersist(
+    const referenced = await referenceMediaBlocksForPersist(
       conv.id,
       conv.createdAt,
       msg.id,
@@ -101,7 +101,7 @@ describe("referenceMediaBlocksForPersist", () => {
       },
     ];
 
-    const referenced = referenceMediaBlocksForPersist(
+    const referenced = await referenceMediaBlocksForPersist(
       conv.id,
       conv.createdAt,
       msg.id,

package/src/__tests__/persist-unsendable-image-downscale.test.ts

@@ -28,8 +28,8 @@ mock.module("../agent/image-optimize.js", () => ({
   // oversized (never undersized), so the min-dimension gate never matches
   // and the rejection-path upscale is never reached.
   isBelowMinDimension: () => false,
-  upscaleImageToMinimum: () => null,
-  optimizeImageForTransport: () => ({
+  upscaleImageToMinimum: async () => null,
+  optimizeImageForTransport: async () => ({
     data: SHRUNK_DATA,
     mediaType: "image/jpeg",
   }),
@@ -133,7 +133,7 @@ describe("persistUnsendableImageDowngrades (downscalable host)", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN the nested block stays an image, rewritten to the downscaled payload
     expect(rewritten).toBe(1);
@@ -159,10 +159,10 @@ describe("persistUnsendableImageDowngrades (downscalable host)", () => {
       JSON.stringify([toolResultWithImage(oversizedPngBase64())]),
       { skipIndexing: true },
     );
-    expect(persistUnsendableImageDowngrades(conv.id)).toBe(1);
+    expect(await persistUnsendableImageDowngrades(conv.id)).toBe(1);
 
     // WHEN the downgrade runs again
-    const secondRun = persistUnsendableImageDowngrades(conv.id);
+    const secondRun = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN nothing further is rewritten
     expect(secondRun).toBe(0);

package/src/__tests__/persist-unsendable-image.test.ts

@@ -132,7 +132,7 @@ describe("persistUnsendableImageDowngrades", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN one message is rewritten with no image block left
     expect(rewritten).toBe(1);
@@ -162,7 +162,7 @@ describe("persistUnsendableImageDowngrades", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN only the rejected original is removed
     expect(rewritten).toBe(1);
@@ -184,7 +184,7 @@ describe("persistUnsendableImageDowngrades", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN nothing is rewritten and the image remains
     expect(rewritten).toBe(0);
@@ -202,7 +202,7 @@ describe("persistUnsendableImageDowngrades", () => {
     });
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN the oversized-payload image is removed
     expect(rewritten).toBe(1);
@@ -224,7 +224,7 @@ describe("persistUnsendableImageDowngrades", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN the undersized image is removed (upscale is a no-op on this host)
     expect(rewritten).toBe(1);
@@ -248,7 +248,7 @@ describe("persistUnsendableImageDowngrades", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN the message is rewritten with the nested image swapped for a note
     expect(rewritten).toBe(1);
@@ -274,7 +274,7 @@ describe("persistUnsendableImageDowngrades", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN nothing is rewritten and the nested image remains
     expect(rewritten).toBe(0);
@@ -302,7 +302,7 @@ describe("persistUnsendableImageDowngrades", () => {
     );
 
     // WHEN the downgrade is persisted
-    const rewritten = persistUnsendableImageDowngrades(conv.id);
+    const rewritten = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN the image survives with its media type corrected to the sniffed one
     expect(rewritten).toBe(1);
@@ -319,7 +319,7 @@ describe("persistUnsendableImageDowngrades", () => {
     });
 
     // AND a second run is a no-op (the corrected block no longer mismatches)
-    expect(persistUnsendableImageDowngrades(conv.id)).toBe(0);
+    expect(await persistUnsendableImageDowngrades(conv.id)).toBe(0);
   });
 
   /** Re-running after a rewrite is a safe no-op (no image blocks remain). */
@@ -332,10 +332,10 @@ describe("persistUnsendableImageDowngrades", () => {
       JSON.stringify([imageBlock(makePngBase64(10000, 10000))]),
       { skipIndexing: true },
     );
-    expect(persistUnsendableImageDowngrades(conv.id)).toBe(1);
+    expect(await persistUnsendableImageDowngrades(conv.id)).toBe(1);
 
     // WHEN the downgrade runs a second time
-    const secondRun = persistUnsendableImageDowngrades(conv.id);
+    const secondRun = await persistUnsendableImageDowngrades(conv.id);
 
     // THEN nothing further is rewritten
     expect(secondRun).toBe(0);
@@ -346,46 +346,46 @@ describe("unsendableImageReplacement", () => {
   /** A still-sendable image must be left alone — never replaced with a note.
    *  This is the gate that keeps the in-memory recovery from discarding valid
    *  screenshots when only one image in the turn was actually oversized. */
-  test("returns null for an image within the provider caps", () => {
+  test("returns null for an image within the provider caps", async () => {
     const sendable = imageBlock(makePngBase64(1024, 768)) as Extract<
       ContentBlock,
       { type: "image" }
     >;
-    expect(unsendableImageReplacement(sendable)).toBeNull();
+    expect(await unsendableImageReplacement(sendable)).toBeNull();
   });
 
   /** An image past the provider caps that cannot be shrunk on this host (fake
    *  PNG that sips cannot decode) collapses to the unsendable note. */
-  test("returns the unsendable note when an oversized image cannot be shrunk", () => {
+  test("returns the unsendable note when an oversized image cannot be shrunk", async () => {
     const oversized = imageBlock(makePngBase64(12000, 9000)) as Extract<
       ContentBlock,
       { type: "image" }
     >;
-    const replacement = unsendableImageReplacement(oversized);
+    const replacement = await unsendableImageReplacement(oversized);
     expect(replacement?.type).toBe("text");
   });
 
   /** An image below the provider's minimum-size floor (rejected with "Could
    *  not process image") that cannot be upscaled on this host collapses to
    *  the unsendable note, same as the oversized direction. */
-  test("returns the unsendable note when an undersized image cannot be upscaled", () => {
+  test("returns the unsendable note when an undersized image cannot be upscaled", async () => {
     const undersized = imageBlock(makePngBase64(16, 14)) as Extract<
       ContentBlock,
       { type: "image" }
     >;
-    const replacement = unsendableImageReplacement(undersized);
+    const replacement = await unsendableImageReplacement(undersized);
     expect(replacement?.type).toBe("text");
   });
 
   /** A within-limits image whose declared media type disagrees with its bytes
    *  is relabeled with the sniffed type instead of being noted out. */
-  test("relabels a mislabeled image with its sniffed media type", () => {
+  test("relabels a mislabeled image with its sniffed media type", async () => {
     const pngData = makePngBase64(1024, 768);
     const mislabeled = imageBlock(pngData, "image/jpeg") as Extract<
       ContentBlock,
       { type: "image" }
     >;
-    const replacement = unsendableImageReplacement(mislabeled);
+    const replacement = await unsendableImageReplacement(mislabeled);
     expect(replacement).toMatchObject({
       type: "image",
       source: { type: "base64", media_type: "image/png", data: pngData },
@@ -394,9 +394,9 @@ describe("unsendableImageReplacement", () => {
 
   /** Relabeling a persisted (workspace_ref) image keeps the reference shape —
    *  inlining it would bake the full payload into the stored message row. */
-  test("relabels a mislabeled workspace_ref without inlining the payload", () => {
+  test("relabels a mislabeled workspace_ref without inlining the payload", async () => {
     const pngData = makePngBase64(1024, 768);
-    const stored = uploadAttachment("photo.png", "image/png", pngData);
+    const stored = await uploadAttachment("photo.png", "image/png", pngData);
     const mislabeledRef = {
       type: "image",
       source: {
@@ -407,7 +407,7 @@ describe("unsendableImageReplacement", () => {
       },
     } as Extract<ContentBlock, { type: "image" }>;
 
-    const replacement = unsendableImageReplacement(mislabeledRef);
+    const replacement = await unsendableImageReplacement(mislabeledRef);
 
     expect(replacement).toMatchObject({
       type: "image",
@@ -419,7 +419,7 @@ describe("unsendableImageReplacement", () => {
     });
     // AND the corrected reference no longer matches on a second pass
     expect(
-      unsendableImageReplacement(
+      await unsendableImageReplacement(
         replacement as Extract<ContentBlock, { type: "image" }>,
       ),
     ).toBeNull();

package/src/__tests__/persona-resolver.test.ts

@@ -63,6 +63,8 @@ function seedVellumGuardian(userFile: string | null): void {
 
 mock.module("../util/platform.js", () => ({
   getWorkspaceDir: () => mockWorkspaceDir,
+  getWorkspacePromptPath: (filename: string) =>
+    join(mockWorkspaceDir, "prompts", filename),
 }));
 
 mock.module("../contacts/contact-store.js", () => ({
@@ -96,6 +98,7 @@ mock.module("../contacts/guardian-delivery-reader.js", () => ({
 // Import AFTER mocks so the module under test binds to the stubbed
 // implementations.
 import { getGuardianDelivery } from "../contacts/guardian-delivery-reader.js";
+import { resolveUserName } from "../daemon/identity-helpers.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
 import {
   ensureGuardianPersonaFile,
@@ -408,3 +411,154 @@ describe("resolveUserSlug (guardian trust WITH requester identity)", () => {
     expect(resolveUserSlug(trustContext)).toBeNull();
   });
 });
+
+// ── resolveUserSlug — guardian bound on a non-vellum channel ───────
+//
+// warmGuardianBindings warms both the channel-filtered and unfiltered cache
+// keys, but a guardian may be bound only on a non-vellum channel (phone,
+// Telegram). A guardian-class turn sourced elsewhere must still resolve that
+// guardian instead of silently landing on users/default.md.
+
+describe("resolveUserSlug (guardian bound on a non-vellum channel)", () => {
+  test("falls back to the any-channel guardian when the source channel has none", () => {
+    mockGuardianDeliveries = [
+      { channelType: "telegram", address: "guardian-tg", status: "active" },
+    ];
+    mockContactsByAddress["telegram:guardian-tg"] = { userFile: "alice.md" };
+
+    const trustContext = {
+      sourceChannel: "vellum",
+      trustClass: "guardian",
+    } as TrustContext;
+
+    expect(resolveUserSlug(trustContext)).toBe("alice");
+  });
+
+  test("any-channel guardian with no userFile resolves the guardian.md fallback", () => {
+    mockGuardianDeliveries = [
+      { channelType: "telegram", address: "guardian-tg", status: "active" },
+    ];
+    mockContactsByAddress["telegram:guardian-tg"] = { userFile: null };
+
+    const trustContext = {
+      sourceChannel: "vellum",
+      trustClass: "guardian",
+    } as TrustContext;
+
+    expect(resolveUserSlug(trustContext)).toBe("guardian");
+  });
+});
+
+// ── resolveUserSlug — cold cache then construction-time warm ───────
+//
+// The exact shape scheduled tasks and memory consolidation pass through
+// resolveInitialSystemPrompt: guardian class, no requester identity, built in
+// a worker process whose guardian-delivery cache starts cold.
+
+describe("resolveUserSlug (cold cache, background shape)", () => {
+  test("misses on a cold cache, resolves the guardian after the construction-time warm", async () => {
+    pendingWarmDeliveries = [
+      { channelType: "vellum", address: "vellum:self", status: "active" },
+    ];
+    mockContactsByAddress["vellum:vellum:self"] = { userFile: "alice.md" };
+
+    const trustContext = {
+      sourceChannel: "vellum",
+      trustClass: "guardian",
+    } as TrustContext;
+
+    // Cold: the sync peek finds nothing and the slug falls back to default.
+    expect(resolveUserSlug(trustContext)).toBeNull();
+
+    // resolveInitialSystemPrompt warms guardian bindings for guardian-class
+    // contexts before building; afterwards the same resolution succeeds.
+    await getGuardianDelivery({ channelTypes: ["vellum"] });
+
+    expect(resolveUserSlug(trustContext)).toBe("alice");
+  });
+});
+
+// ── resolveUserName — guardian-preferred display name ──────────────
+//
+// The sweep job and v2 router address the user by name in their prompts. The
+// name must come from the guardian's own persona file when one is resolvable,
+// falling back to users/default.md.
+
+describe("resolveUserName", () => {
+  test("prefers the Name label from the guardian's own persona file over default.md", () => {
+    seedVellumGuardian("alice.md");
+    const usersDir = join(mockWorkspaceDir, "users");
+    mkdirSync(usersDir, { recursive: true });
+    writeFileSync(join(usersDir, "alice.md"), "**Name:** Alice\n", "utf-8");
+    writeFileSync(
+      join(usersDir, "default.md"),
+      "**Name:** Default User\n",
+      "utf-8",
+    );
+
+    expect(resolveUserName(mockWorkspaceDir)).toBe("Alice");
+  });
+
+  test("reads the onboarding-written Preferred name bullet", () => {
+    seedVellumGuardian("alice.md");
+    const usersDir = join(mockWorkspaceDir, "users");
+    mkdirSync(usersDir, { recursive: true });
+    writeFileSync(
+      join(usersDir, "alice.md"),
+      "# User Profile\n\n## Onboarding Context\n\n- **Preferred name:** Ali\n",
+      "utf-8",
+    );
+
+    expect(resolveUserName(mockWorkspaceDir)).toBe("Ali");
+  });
+
+  test("reads the scaffold's filled Preferred name/reference line", () => {
+    seedVellumGuardian("alice.md");
+    const usersDir = join(mockWorkspaceDir, "users");
+    mkdirSync(usersDir, { recursive: true });
+    writeFileSync(
+      join(usersDir, "alice.md"),
+      "- Preferred name/reference: Alice\n- Pronouns: she/her\n",
+      "utf-8",
+    );
+
+    expect(resolveUserName(mockWorkspaceDir)).toBe("Alice");
+  });
+
+  test("an unfilled scaffold does not swallow the next line and falls back to default.md", () => {
+    seedVellumGuardian("alice.md");
+    const usersDir = join(mockWorkspaceDir, "users");
+    mkdirSync(usersDir, { recursive: true });
+    // The bare scaffold: every label present, every value unfilled.
+    ensureGuardianPersonaFile("alice.md");
+    writeFileSync(join(usersDir, "default.md"), "**Name:** Bob\n", "utf-8");
+
+    expect(resolveUserName(mockWorkspaceDir)).toBe("Bob");
+  });
+
+  test("a declined_by_user sentinel is not used as a name", () => {
+    seedVellumGuardian("alice.md");
+    const usersDir = join(mockWorkspaceDir, "users");
+    mkdirSync(usersDir, { recursive: true });
+    writeFileSync(
+      join(usersDir, "alice.md"),
+      "- Preferred name/reference: declined_by_user\n",
+      "utf-8",
+    );
+    writeFileSync(join(usersDir, "default.md"), "**Name:** Bob\n", "utf-8");
+
+    expect(resolveUserName(mockWorkspaceDir)).toBe("Bob");
+  });
+
+  test("falls back to default.md when no guardian resolves", () => {
+    const usersDir = join(mockWorkspaceDir, "users");
+    mkdirSync(usersDir, { recursive: true });
+    writeFileSync(join(usersDir, "default.md"), "**Name:** Bob\n", "utf-8");
+
+    expect(resolveUserName(mockWorkspaceDir)).toBe("Bob");
+  });
+
+  test("returns null when neither file yields a name", () => {
+    expect(resolveUserName(mockWorkspaceDir)).toBeNull();
+  });
+});