@vellumai/assistant 0.8.2 → 0.8.3

package/src/daemon/lifecycle.ts

@@ -49,6 +49,7 @@ import { startMemoryJobsWorker } from "../memory/jobs-worker.js";
 import { initQdrantClient, resolveQdrantUrl } from "../memory/qdrant-client.js";
 import { QdrantManager } from "../memory/qdrant-manager.js";
 import { rotateToolInvocations } from "../memory/tool-usage-store.js";
+import { sweepConceptPageFrontmatter } from "../memory/v2/frontmatter-sweep.js";
 import {
   emitNotificationSignal,
   registerBroadcastFn,
@@ -96,10 +97,6 @@ import {
 import { WorkspaceHeartbeatService } from "../workspace/heartbeat-service.js";
 import { WORKSPACE_MIGRATIONS } from "../workspace/migrations/registry.js";
 import { runWorkspaceMigrations } from "../workspace/migrations/runner.js";
-import {
-  createApprovalConversationGenerator,
-  createApprovalCopyGenerator,
-} from "./approval-generators.js";
 import {
   cleanupPidFile,
   cleanupPidFileIfOwner,
@@ -111,10 +108,6 @@ import {
   stopDiskPressureGuard,
 } from "./disk-pressure-guard.js";
 import { bootstrapPlugins } from "./external-plugins-bootstrap.js";
-import {
-  createGuardianActionCopyGenerator,
-  createGuardianFollowUpConversationGenerator,
-} from "./guardian-action-generators.js";
 import { backfillSlackInjectionTemplates } from "./handlers/config-slack-channel.js";
 import { installAssistantSymlink } from "./install-symlink.js";
 import {
@@ -322,6 +315,35 @@ export async function runDaemon(): Promise<void> {
     const signingKey = resolveSigningKey();
     initAuthSigningKey(signingKey);
 
+    // Start the runtime HTTP server early so /healthz answers ASAP.
+    let runtimeHttp: RuntimeHttpServer | null = null;
+    const httpPort = getRuntimeHttpPort();
+    const httpHostname = getRuntimeHttpHost();
+    log.info({ httpPort }, "Daemon startup: starting runtime HTTP server");
+
+    runtimeHttp = new RuntimeHttpServer({
+      port: httpPort,
+      hostname: httpHostname,
+    });
+
+    // Isolated try/catch around start() — a bind failure (port in use,
+    // permission denied, fd exhaustion) must not tear down the rest of
+    // daemon startup. The daemon falls back to IPC-only operation when
+    // runtimeHttp is null.
+    try {
+      await runtimeHttp.start();
+      log.info(
+        { port: httpPort, hostname: httpHostname },
+        "Daemon startup: runtime HTTP server listening",
+      );
+    } catch (err) {
+      log.warn(
+        { err, port: httpPort },
+        "Failed to start runtime HTTP server, continuing without it",
+      );
+      runtimeHttp = null;
+    }
+
     // Pre-populate feature flag overrides so subsequent sync
     // isAssistantFeatureFlagEnabled() calls have data. Fired non-blocking
     // so a slow or unreachable gateway doesn't delay daemon startup (the
@@ -861,34 +883,16 @@ export async function runDaemon(): Promise<void> {
           })();
         }
 
-        // Build the BM25 corpus stats (per-token document frequencies and
-        // average document length) used by the v2 sparse channel, then
-        // re-seed v2 skill entries so any skill vectors written during the
-        // cold-start window with the legacy TF encoder get rewritten with
-        // stemmed BM25 vectors. Fire-and-forget for the same reason as PKB
-        // reconcile — the stats and skill reseed are optional optimizations,
-        // never boot-blocking dependencies.
         void rebuildBm25CorpusStatsAndReseedSkills(config);
 
-        // Validate every concept page's frontmatter against the strict
-        // schema and emit a `warn` per offender. Surfaces schema drift
-        // (unknown keys, type mismatches) at boot time instead of waiting
-        // for the failure to manifest as a silent V2 retrieval no-op when
-        // a bad page first lands in a conversation's top-K. Fire-and-forget
-        // and the sweep itself never throws — defense in depth via the
-        // outer try/catch.
-        void (async () => {
-          try {
-            const { sweepConceptPageFrontmatter } =
-              await import("../memory/v2/frontmatter-sweep.js");
-            await sweepConceptPageFrontmatter(getWorkspaceDir());
-          } catch (err) {
-            log.warn(
-              { err },
-              "Concept page frontmatter sweep threw — continuing startup",
-            );
-          }
-        })();
+        try {
+          await sweepConceptPageFrontmatter(config, getWorkspaceDir());
+        } catch (err) {
+          log.warn(
+            { err },
+            "Concept page frontmatter sweep threw — continuing startup",
+          );
+        }
       }
 
       log.info("Daemon startup: starting memory worker");
@@ -1009,24 +1013,12 @@ export async function runDaemon(): Promise<void> {
       },
     );
 
-    // Start the runtime HTTP server for optional REST API access.
-    // Defaults to port 7821.
-    let runtimeHttp: RuntimeHttpServer | null = null;
-    const httpPort = getRuntimeHttpPort();
-    log.info({ httpPort }, "Daemon startup: starting runtime HTTP server");
-
-    const hostname = getRuntimeHttpHost();
-
-    runtimeHttp = new RuntimeHttpServer({
-      port: httpPort,
-      hostname,
-      approvalCopyGenerator: createApprovalCopyGenerator(),
-      approvalConversationGenerator: createApprovalConversationGenerator(),
-      guardianActionCopyGenerator: createGuardianActionCopyGenerator(),
-      guardianFollowUpConversationGenerator:
-        createGuardianFollowUpConversationGenerator(),
-    });
-
+    // Wire up the runtime HTTP server's deferred dependencies. The server
+    // itself was bound early in runDaemon (right after the auth signing key
+    // was loaded) so /healthz and /readyz already answer 200 OK; these
+    // registrations attach the live DaemonServer / CES / relay handlers to
+    // the running routes. They're module-level state, so they're effective
+    // even when the HTTP server failed to bind (IPC clients still work).
     registerSecretsDeps({
       getCesClient: () => server.getCesClient(),
       onProviderCredentialsChanged: () =>
@@ -1043,8 +1035,9 @@ export async function runDaemon(): Promise<void> {
       log.warn({ err }, "Background Qdrant init failed"),
     );
 
-    // Inject voice bridge deps BEFORE attempting to start the HTTP server.
-    // The bridge must be available even when the HTTP server fails to bind.
+    // Inject voice bridge deps so route handlers + the relay pipeline can
+    // resolve a conversation by ID once a call lands. Module-level state,
+    // so available even when the HTTP server failed to bind.
     setVoiceBridgeDeps({
       getOrCreateConversation: (conversationId, _transport) =>
         server.getConversationForMessages(conversationId),
@@ -1063,7 +1056,6 @@ export async function runDaemon(): Promise<void> {
       },
     });
     try {
-      await runtimeHttp.start();
       setRelayBroadcast((msg) => broadcastMessage(msg));
       setPointerMessageProcessor(
         async (conversationId, instruction, requiredFacts) => {
@@ -1201,14 +1193,10 @@ export async function runDaemon(): Promise<void> {
         },
       );
       server.broadcastStatus();
-      log.info(
-        { port: httpPort, hostname },
-        "Daemon startup: runtime HTTP server listening",
-      );
     } catch (err) {
       log.warn(
-        { err, port: httpPort },
-        "Failed to start runtime HTTP server, continuing without it",
+        { err },
+        "Failed to wire runtime HTTP server deps, continuing without them",
       );
       runtimeHttp = null;
     }

package/src/daemon/memory-v2-startup.ts

@@ -35,6 +35,19 @@ export function maybeSeedMemoryV2Skills(config: AssistantConfig): void {
     );
 }
 
+/**
+ * Fire-and-forget seed of the v2 CLI-subcommand entries (indexed alongside
+ * concept pages and skills in `memory_v2_concept_pages` under the
+ * `cli-commands/<name>` slug prefix). Dynamic import keeps v2 code out of the
+ * startup graph when the gate is off. Never awaits — startup must not block.
+ */
+export function maybeSeedMemoryV2CliCommands(config: AssistantConfig): void {
+  if (!config.memory.v2.enabled) return;
+  void import("../memory/v2/cli-command-store.js")
+    .then(({ seedV2CliCommandEntries }) => seedV2CliCommandEntries())
+    .catch((err) => log.warn({ err }, "Failed to seed v2 CLI-command entries"));
+}
+
 /**
  * Build the v2 BM25 corpus stats (per-token document frequencies + avg doc
  * length), then re-seed the v2 skill entries so any skills written during
@@ -56,6 +69,8 @@ export function maybeSeedMemoryV2Skills(config: AssistantConfig): void {
 export async function rebuildBm25CorpusStatsAndReseedSkills(
   config: AssistantConfig,
 ): Promise<void> {
+  if (!config.memory.v2.enabled) return;
+
   try {
     const { rebuildConceptPageCorpusStats } =
       await import("../memory/v2/sparse-bm25.js");
@@ -69,19 +84,40 @@ export async function rebuildBm25CorpusStatsAndReseedSkills(
     return;
   }
 
-  if (!config.memory.v2.enabled) return;
-  try {
-    const { seedV2SkillEntries } = await import("../memory/v2/skill-store.js");
-    await seedV2SkillEntries({ throwOnError: true });
-    log.info(
-      "Memory v2 skill embeddings re-seeded with BM25 vectors after corpus-stats build",
-    );
-  } catch (err) {
-    log.warn(
-      { err },
-      "Failed to re-seed v2 skill entries after BM25 corpus-stats build — skills seeded during cold start may keep TF-only sparse vectors until next reseed",
-    );
-  }
+  // Skills and CLI commands share the unified collection but are independent
+  // catalogs — reseed in parallel so the second one isn't gated on the first.
+  await Promise.all([
+    (async () => {
+      try {
+        const { seedV2SkillEntries } =
+          await import("../memory/v2/skill-store.js");
+        await seedV2SkillEntries({ throwOnError: true });
+        log.info(
+          "Memory v2 skill embeddings re-seeded with BM25 vectors after corpus-stats build",
+        );
+      } catch (err) {
+        log.warn(
+          { err },
+          "Failed to re-seed v2 skill entries after BM25 corpus-stats build — skills seeded during cold start may keep TF-only sparse vectors until next reseed",
+        );
+      }
+    })(),
+    (async () => {
+      try {
+        const { seedV2CliCommandEntries } =
+          await import("../memory/v2/cli-command-store.js");
+        await seedV2CliCommandEntries({ throwOnError: true });
+        log.info(
+          "Memory v2 CLI-command embeddings re-seeded with BM25 vectors after corpus-stats build",
+        );
+      } catch (err) {
+        log.warn(
+          { err },
+          "Failed to re-seed v2 CLI-command entries after BM25 corpus-stats build — entries seeded during cold start may keep TF-only sparse vectors until next reseed",
+        );
+      }
+    })(),
+  ]);
 }
 
 /**

package/src/daemon/message-types/notifications.ts

@@ -14,6 +14,20 @@ export interface NotificationIntent {
    * Clients not bound to this guardian should ignore the notification.
    */
   targetGuardianPrincipalId?: string;
+  /**
+   * When true, the client must NOT post this intent to the OS notification
+   * surface (`UNUserNotificationCenter` on macOS). Non-banner side effects
+   * (guardian filtering, fallback dedup, mark-unseen + history catch-up on
+   * the paired conversation) still run. The home-feed inbox entry is
+   * written independently by `home-feed-side-effect.ts` and is unaffected
+   * by this flag.
+   *
+   * Set by the server based on `attentionHints.urgency`: true for
+   * `low`/`medium`, false for `high`/`critical`. The notification center
+   * is the always-on canonical inbox; the OS banner is reserved for
+   * signals the user opted into push for (urgency >= high).
+   */
+  silent?: boolean;
 }
 
 /** Server push — broadcast when a notification creates a new vellum conversation. */
@@ -39,6 +53,13 @@ export interface NotificationConversationCreated {
    * conversation is attributed correctly.
    */
   source?: string;
+  /**
+   * Mirrors `NotificationIntent.silent`. When true the client must not
+   * post a fallback OS banner for this conversation — the sidebar entry
+   * still appears, but the always-on inbox is the only surfaced channel.
+   * Derived from the originating signal's `attentionHints.urgency`.
+   */
+  silent?: boolean;
 }
 
 /** Client ack sent after UNUserNotificationCenter.add() completes (or fails). */

package/src/daemon/pkb-reminder-builder.test.ts

@@ -2,32 +2,24 @@ import { describe, expect, test } from "bun:test";
 
 import { buildPkbReminder } from "./pkb-reminder-builder.js";
 
-// Byte-for-byte fixture of the default (non-relaxed) PKB reminder. Asserted
-// verbatim so that any future edit to the BODY text is caught by tests.
-const BASE_REMINDER_DEFAULT =
-  "<system_reminder>" +
-  "\n**CRITICAL:** Call `remember` this turn for anything concrete the user said — facts, preferences, plans, names, dates, decisions, corrections, felt moments. Default to remembering; skip only obvious noise. This should be your most frequently used tool." +
-  "\nIf you're unsure about something that may live in the workspace — past decisions, prior conversations, files — use `recall` before asking or guessing." +
-  "\n</system_reminder>";
-
-// Byte-for-byte fixture of the relaxed PKB reminder used when the
-// `memory-retrospective` feature flag is on.
-const BASE_REMINDER_RELAXED =
+// Byte-for-byte fixture of the PKB reminder. Asserted verbatim so that any
+// future edit to the BODY text is caught by tests.
+const BASE_REMINDER =
   "<system_reminder>" +
   "\nStay present in this conversation. Use `remember` when something feels worth pausing to mark — corrections (highest priority), plans, decisions, felt moments. You don't have to capture everything in the moment — a retrospective pass reviews this conversation in the background and saves what you didn't capture." +
   "\nIf you're unsure about something that may live in the workspace — past decisions, prior conversations, files — use `recall` before asking or guessing." +
   "\n</system_reminder>";
 
-describe("buildPkbReminder — default body (relaxed=false)", () => {
+describe("buildPkbReminder", () => {
   test("empty hints returns exact base reminder byte-for-byte", () => {
-    expect(buildPkbReminder([], false)).toBe(BASE_REMINDER_DEFAULT);
+    expect(buildPkbReminder([])).toBe(BASE_REMINDER);
   });
 
   test("single hint renders one bullet with no duplicates or trailing blank line", () => {
-    const out = buildPkbReminder(["projects/alpha.md"], false);
+    const out = buildPkbReminder(["projects/alpha.md"]);
     const expected =
       "<system_reminder>" +
-      "\n**CRITICAL:** Call `remember` this turn for anything concrete the user said — facts, preferences, plans, names, dates, decisions, corrections, felt moments. Default to remembering; skip only obvious noise. This should be your most frequently used tool." +
+      "\nStay present in this conversation. Use `remember` when something feels worth pausing to mark — corrections (highest priority), plans, decisions, felt moments. You don't have to capture everything in the moment — a retrospective pass reviews this conversation in the background and saves what you didn't capture." +
       "\nIf you're unsure about something that may live in the workspace — past decisions, prior conversations, files — use `recall` before asking or guessing." +
       "\nBased on the current context, these files look especially relevant:" +
       "\n- projects/alpha.md" +
@@ -44,10 +36,10 @@ describe("buildPkbReminder — default body (relaxed=false)", () => {
 
   test("three hints render all three in order", () => {
     const hints = ["a.md", "sub/b.md", "c/d/e.md"];
-    const out = buildPkbReminder(hints, false);
+    const out = buildPkbReminder(hints);
     const expected =
       "<system_reminder>" +
-      "\n**CRITICAL:** Call `remember` this turn for anything concrete the user said — facts, preferences, plans, names, dates, decisions, corrections, felt moments. Default to remembering; skip only obvious noise. This should be your most frequently used tool." +
+      "\nStay present in this conversation. Use `remember` when something feels worth pausing to mark — corrections (highest priority), plans, decisions, felt moments. You don't have to capture everything in the moment — a retrospective pass reviews this conversation in the background and saves what you didn't capture." +
       "\nIf you're unsure about something that may live in the workspace — past decisions, prior conversations, files — use `recall` before asking or guessing." +
       "\nBased on the current context, these files look especially relevant:" +
       "\n- a.md" +
@@ -67,7 +59,7 @@ describe("buildPkbReminder — default body (relaxed=false)", () => {
 
   test("hints with special chars (< and &) are emitted verbatim (no escaping)", () => {
     const hints = ["weird<name>.md", "foo&bar.md"];
-    const out = buildPkbReminder(hints, false);
+    const out = buildPkbReminder(hints);
     expect(out).toContain("- weird<name>.md");
     expect(out).toContain("- foo&bar.md");
     // Ensure no HTML-style escaping happened.
@@ -75,38 +67,3 @@ describe("buildPkbReminder — default body (relaxed=false)", () => {
     expect(out).not.toContain("&amp;");
   });
 });
-
-describe("buildPkbReminder — relaxed body (relaxed=true)", () => {
-  test("empty hints returns the relaxed base reminder byte-for-byte", () => {
-    expect(buildPkbReminder([], true)).toBe(BASE_REMINDER_RELAXED);
-  });
-
-  test("relaxed BODY does NOT contain the default high-pressure phrasing", () => {
-    const out = buildPkbReminder([], true);
-    expect(out).not.toContain("**CRITICAL:**");
-    expect(out).not.toContain("most frequently used tool");
-    expect(out).not.toContain("Default to remembering");
-  });
-
-  test("relaxed BODY mentions the retrospective backstop framing", () => {
-    const out = buildPkbReminder([], true);
-    expect(out).toContain("Stay present");
-    expect(out).toContain("retrospective pass");
-  });
-
-  test("hints render below the relaxed body in the same shape as default", () => {
-    const out = buildPkbReminder(["projects/alpha.md"], true);
-    expect(out).toContain("- projects/alpha.md");
-    expect(out).toContain(
-      "Based on the current context, these files look especially relevant:",
-    );
-    // Should still close cleanly with no double newline before the tag.
-    expect(out.includes("\n\n</system_reminder>")).toBe(false);
-  });
-});
-
-describe("buildPkbReminder — relaxed vs default differ", () => {
-  test("the two BODY variants are NOT byte-identical", () => {
-    expect(buildPkbReminder([], false)).not.toBe(buildPkbReminder([], true));
-  });
-});

package/src/daemon/pkb-reminder-builder.ts

@@ -1,8 +1,4 @@
-const BODY_DEFAULT =
-  "\n**CRITICAL:** Call `remember` this turn for anything concrete the user said — facts, preferences, plans, names, dates, decisions, corrections, felt moments. Default to remembering; skip only obvious noise. This should be your most frequently used tool." +
-  "\nIf you're unsure about something that may live in the workspace — past decisions, prior conversations, files — use `recall` before asking or guessing.";
-
-const BODY_RELAXED =
+const BODY =
   "\nStay present in this conversation. Use `remember` when something feels worth pausing to mark — corrections (highest priority), plans, decisions, felt moments. You don't have to capture everything in the moment — a retrospective pass reviews this conversation in the background and saves what you didn't capture." +
   "\nIf you're unsure about something that may live in the workspace — past decisions, prior conversations, files — use `recall` before asking or guessing.";
 
@@ -15,23 +11,12 @@ const BODY_RELAXED =
  * hint. Hints are emitted verbatim — they are trusted internal paths, not
  * user input, so no escaping is performed.
  *
- * The `relaxed` flag selects between the default high-pressure body and the
- * relaxed "judgment framing" body used when the `memory-retrospective`
- * feature flag is on. With the flag on, the in-conversation remember pressure
- * eases because the retrospective is the backstop. Callers must pass
- * `relaxed` explicitly — no default — so the contract is visible at every
- * call site.
- *
  * Caller is responsible for capping the hints array at 3 entries.
  */
-export function buildPkbReminder(
-  hints: ReadonlyArray<string>,
-  relaxed: boolean,
-): string {
-  const body = relaxed ? BODY_RELAXED : BODY_DEFAULT;
+export function buildPkbReminder(hints: ReadonlyArray<string>): string {
   if (hints.length === 0) {
-    return `<system_reminder>${body}\n</system_reminder>`;
+    return `<system_reminder>${BODY}\n</system_reminder>`;
   }
   const bullets = hints.map((h) => `- ${h}`).join("\n");
-  return `<system_reminder>${body}\nBased on the current context, these files look especially relevant:\n${bullets}\n</system_reminder>`;
+  return `<system_reminder>${BODY}\nBased on the current context, these files look especially relevant:\n${bullets}\n</system_reminder>`;
 }

package/src/daemon/process-message.ts

@@ -31,6 +31,7 @@ import { updateMetaFile } from "../memory/conversation-disk-view.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import { publishConversationMessagesChanged } from "../runtime/sync/resource-sync-events.js";
+import { getSubagentManager } from "../subagent/index.js";
 import { getLogger } from "../util/logger.js";
 import type { Conversation } from "./conversation.js";
 import {
@@ -455,6 +456,7 @@ export async function processMessage(
 
   if (options?.isInteractive === true) {
     conversation.updateClient(broadcastMessage, false);
+    getSubagentManager().updateParentSender(conversationId, broadcastMessage);
   }
 
   try {
@@ -521,6 +523,7 @@ export async function processMessageInBackground(
 
   if (options?.isInteractive === true) {
     conversation.updateClient(broadcastMessage, false);
+    getSubagentManager().updateParentSender(conversationId, broadcastMessage);
   }
 
   conversation.setSlackRuntimeContextNotice(options?.slackRuntimeContextNotice);

package/src/daemon/skill-memory-refresh.ts

@@ -5,7 +5,10 @@ import {
   seedUninstalledCatalogSkillMemories,
 } from "../memory/graph/capability-seed.js";
 import { getLogger } from "../util/logger.js";
-import { maybeSeedMemoryV2Skills } from "./memory-v2-startup.js";
+import {
+  maybeSeedMemoryV2CliCommands,
+  maybeSeedMemoryV2Skills,
+} from "./memory-v2-startup.js";
 
 const log = getLogger("skill-memory-refresh");
 
@@ -14,6 +17,7 @@ export function refreshSkillCapabilityMemories(
 ): void {
   seedSkillGraphNodes();
   maybeSeedMemoryV2Skills(config);
+  maybeSeedMemoryV2CliCommands(config);
   void seedUninstalledCatalogSkillMemories()
     .then(() => {
       // Re-run after the async catalog fetch populates the cache so stale

package/src/daemon/wake-target-adapter.ts

@@ -135,6 +135,8 @@ function translateAgentEventToServerMessage(
     case "input_json_delta":
     case "usage":
     case "error":
+    case "provider_error":
+    case "agent_loop_exit":
       return null;
   }
 }

package/src/export/__tests__/transcript-formatter.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import { z } from "zod";
+
+type TestMessage = {
+  id: string;
+  conversationId: string;
+  role: string;
+  content: string;
+  createdAt: number;
+  metadata: string | null;
+};
+
+const parentMessages: TestMessage[] = [
+  {
+    id: "msg-parent-1",
+    conversationId: "parent-conv",
+    role: "user",
+    content: JSON.stringify([{ type: "text", text: "go research foo" }]),
+    createdAt: 1_700_000_000_000,
+    metadata: null,
+  },
+  {
+    id: "msg-parent-2",
+    conversationId: "parent-conv",
+    role: "assistant",
+    content: JSON.stringify([{ type: "text", text: "spawning subagent" }]),
+    createdAt: 1_700_000_001_000,
+    metadata: JSON.stringify({
+      subagentNotification: {
+        subagentId: "sa-1",
+        label: "research-foo",
+        status: "completed",
+        conversationId: "child-conv-1",
+      },
+    }),
+  },
+];
+
+const childMessages: TestMessage[] = [
+  {
+    id: "msg-child-1",
+    conversationId: "child-conv-1",
+    role: "user",
+    content: JSON.stringify([
+      { type: "text", text: "Objective: research foo and report back." },
+    ]),
+    createdAt: 1_700_000_002_000,
+    metadata: null,
+  },
+  {
+    id: "msg-child-2",
+    conversationId: "child-conv-1",
+    role: "assistant",
+    content: JSON.stringify([
+      { type: "text", text: "I found that foo is a bar." },
+    ]),
+    createdAt: 1_700_000_003_000,
+    metadata: null,
+  },
+];
+
+const messageMetadataSchema = z.object({
+  subagentNotification: z
+    .object({
+      subagentId: z.string(),
+      label: z.string(),
+      status: z.enum(["running", "completed", "failed", "aborted"]),
+      conversationId: z.string().optional(),
+    })
+    .optional(),
+});
+
+mock.module("../../memory/conversation-crud.js", () => ({
+  getConversation: (_id: string) => null,
+  getMessages: (id: string) =>
+    id === "child-conv-1" ? childMessages : parentMessages,
+  messageMetadataSchema,
+}));
+
+mock.module("../../util/truncate.js", () => ({
+  truncate: (s: string) => s,
+}));
+
+mock.module("../../daemon/date-context.js", () => ({
+  formatLocalTimestamp: (_ts: number, _tz?: string) => "TIME",
+}));
+
+const { formatMessageSliceForTranscript } =
+  await import("../transcript-formatter.js");
+
+describe("formatMessageSliceForTranscript subagent labels", () => {
+  test("embedded subagent transcripts render with generic role labels even when parent display names are provided", () => {
+    const out = formatMessageSliceForTranscript(parentMessages, {
+      assistantName: "Bob",
+      userName: "Alice",
+    });
+
+    // Parent messages use the provided display names.
+    expect(out).toContain("## Alice (TIME)");
+    expect(out).toContain("## Bob (TIME)");
+
+    // Subagent block headers must use generic labels — the child "user" message
+    // is actually the parent assistant's objective, so labeling it "Alice"
+    // would misattribute the assistant's tasking text to the human user.
+    expect(out).toContain("### Subagent: research-foo (completed)");
+    expect(out).toContain("> **User** (TIME)");
+    expect(out).toContain("> **Assistant** (TIME)");
+    expect(out).not.toContain("> **Alice**");
+    expect(out).not.toContain("> **Bob**");
+  });
+
+  test("without display-name options, parent and subagent both use generic labels", () => {
+    const out = formatMessageSliceForTranscript(parentMessages);
+
+    expect(out).toContain("## User (TIME)");
+    expect(out).toContain("## Assistant (TIME)");
+    expect(out).toContain("> **User** (TIME)");
+    expect(out).toContain("> **Assistant** (TIME)");
+  });
+});