@vellumai/assistant 0.8.1 → 0.8.3

package/src/memory/v2/__tests__/injection.test.ts

@@ -161,6 +161,38 @@ mock.module("../skill-store.js", () => ({
   listSkillEntries: () => Array.from(skillState.entries.values()),
 }));
 
+// ---------------------------------------------------------------------------
+// CLI-command-store mock
+// ---------------------------------------------------------------------------
+//
+// Mirrors the skill-store mock. CLI subcommand synthetic entries flow through
+// the unified pipeline under the `cli-commands/<name>` slug prefix and render
+// under `### CLI Commands You Can Use`. Tests stage `cliCommandState.entries`
+// and rely on `stageTurn` plumbing to land slugs in the candidate set.
+
+interface CliCommandEntryStub {
+  id: string;
+  description: string;
+  content: string;
+}
+
+const cliCommandState = {
+  entries: new Map<string, CliCommandEntryStub>(),
+};
+
+mock.module("../cli-command-store.js", () => ({
+  getCliCommandCapability: (idOrSlug: string) => {
+    const id = idOrSlug.startsWith("cli-commands/")
+      ? idOrSlug.slice("cli-commands/".length)
+      : idOrSlug;
+    return cliCommandState.entries.get(id) ?? null;
+  },
+  isCliCommandSlug: (slug: string) => slug.startsWith("cli-commands/"),
+  CLI_COMMAND_SLUG_PREFIX: "cli-commands/",
+  cliCommandSlugFor: (name: string) => `cli-commands/${name}`,
+  listCliCommandEntries: () => Array.from(cliCommandState.entries.values()),
+}));
+
 // ---------------------------------------------------------------------------
 // Activation-log store mock
 // ---------------------------------------------------------------------------
@@ -357,7 +389,7 @@ const { getSqliteFrom } = await import("../../db-connection.js");
 const { migrateActivationState } =
   await import("../../migrations/232-activation-state.js");
 const schema = await import("../../schema.js");
-const { evictCompactedTurns, hydrate, save } =
+const { clearEverInjected, hydrate, save } =
   await import("../activation-store.js");
 const { injectMemoryV2Block } = await import("../injection.js");
 const { _resetMemoryV2QdrantForTests } = await import("../qdrant.js");
@@ -484,6 +516,7 @@ function resetState(): void {
   state.queryResponses.dense.length = 0;
   state.queryResponses.sparse.length = 0;
   skillState.entries.clear();
+  cliCommandState.entries.clear();
   telemetryState.recordCalls.length = 0;
   telemetryState.recordShouldThrow = false;
   pageStoreState.failingSlugs.clear();
@@ -503,6 +536,13 @@ function stageSkills(entries: SkillEntry[]): void {
   }
 }
 
+/** Stage cli-command-store cache entries for the upcoming render. */
+function stageCliCommands(entries: CliCommandEntryStub[]): void {
+  for (const entry of entries) {
+    cliCommandState.entries.set(entry.id, entry);
+  }
+}
+
 let db: DrizzleDb;
 beforeEach(() => {
   db = createTestDb();
@@ -653,10 +693,10 @@ describe("injectMemoryV2Block", () => {
       config: makeConfig(),
     });
 
-    // Simulate compaction: drop all everInjected entries with turn <= 1.
+    // Simulate compaction: clear the entire everInjected list.
     const beforeEvict = await hydrate(db, "conv-1");
     expect(beforeEvict).not.toBeNull();
-    const afterEvict = evictCompactedTurns(beforeEvict!, 1);
+    const afterEvict = clearEverInjected(beforeEvict!);
     expect(afterEvict.everInjected).toEqual([]);
     await save(db, "conv-1", afterEvict);
 
@@ -879,17 +919,17 @@ describe("injectMemoryV2Block", () => {
   // Unified pool — skills as `skills/<id>` slugs
   // ---------------------------------------------------------------------------
 
-  test("renders a skill-only block via the skills/ slug prefix", async () => {
+  test("renders a retrieved skills/<id> slug under Skills You Can Use", async () => {
     // No concept-page candidates this turn — the only ANN hit is a skill
     // slug. The render path branches on `skills/` prefix: it pulls the
     // entry from the skill-store cache (mocked) and emits the bullet under
     // the `### Skills You Can Use` subsection.
-    stageTurn([{ slug: "skills/example-skill-a", denseScore: 0.9 }]);
+    stageTurn([{ slug: "skills/retrieved-skill", denseScore: 0.9 }]);
     stageSkills([
       {
-        id: "example-skill-a",
+        id: "retrieved-skill",
         content:
-          'The "Example Skill A" skill (example-skill-a) is available. Helps with examples.',
+          'The "Retrieved Skill" skill (retrieved-skill) is available. Helps with retrieved skills.',
       },
     ]);
 
@@ -904,16 +944,18 @@ describe("injectMemoryV2Block", () => {
       config: makeConfig(),
     });
 
-    expect(result.toInject).toEqual(["skills/example-skill-a"]);
+    expect(result.toInject).toEqual(["skills/retrieved-skill"]);
     expect(result.block).not.toBeNull();
     expect(result.block).not.toContain("<memory>");
     expect(result.block).not.toContain("</memory>");
     expect(result.block).not.toContain("## What I Remember Right Now");
     expect(result.block).not.toContain("# memory/concepts/alice-vscode.md");
-    expect(result.block).toContain("### Skills You Can Use");
-    expect(result.block).toContain(
-      '- The "Example Skill A" skill (example-skill-a) is available. Helps with examples. → use skill_load to activate',
+    const headerIdx = result.block!.indexOf("### Skills You Can Use");
+    const skillIdx = result.block!.indexOf(
+      '- The "Retrieved Skill" skill (retrieved-skill) is available. Helps with retrieved skills. → use skill_load to activate',
     );
+    expect(headerIdx).toBeGreaterThan(-1);
+    expect(skillIdx).toBeGreaterThan(headerIdx);
   });
 
   test("renders concept-page sections before the skills subsection in mixed blocks", async () => {
@@ -1058,6 +1100,153 @@ describe("injectMemoryV2Block", () => {
     expect(result.block).toBeNull();
   });
 
+  // ---------------------------------------------------------------------------
+  // CLI-command synthetic entries — same unified-pool plumbing as skills.
+  // ---------------------------------------------------------------------------
+
+  test("renders a retrieved cli-commands/<name> slug under CLI Commands You Can Use", async () => {
+    stageTurn([{ slug: "cli-commands/attachment", denseScore: 0.9 }]);
+    stageCliCommands([
+      {
+        id: "attachment",
+        description: "Manage file attachments for conversations",
+        content: 'The "assistant attachment" CLI command is available...',
+      },
+    ]);
+
+    const result = await injectMemoryV2Block({
+      database: db,
+      conversationId: "conv-1",
+      currentTurn: 1,
+      userMessage: "How do I register a video?",
+      assistantMessage: "",
+      nowText: "Now",
+      messageId: "msg-1",
+      config: makeConfig(),
+    });
+
+    expect(result.toInject).toEqual(["cli-commands/attachment"]);
+    expect(result.block).not.toBeNull();
+    const headerIdx = result.block!.indexOf("### CLI Commands You Can Use");
+    const lineIdx = result.block!.indexOf(
+      "- `assistant attachment`: Manage file attachments for conversations",
+    );
+    expect(headerIdx).toBeGreaterThan(-1);
+    expect(lineIdx).toBeGreaterThan(headerIdx);
+  });
+
+  test("renders concepts, skills, then cli-commands in that order in mixed blocks", async () => {
+    stageTurn([
+      { slug: "alice-vscode", denseScore: 0.95 },
+      { slug: "skills/example-skill-a", denseScore: 0.85 },
+      { slug: "cli-commands/config", denseScore: 0.75 },
+    ]);
+    stageSkills([
+      {
+        id: "example-skill-a",
+        content:
+          'The "Example Skill A" skill (example-skill-a) is available. Helps with examples.',
+      },
+    ]);
+    stageCliCommands([
+      {
+        id: "config",
+        description: "Manage configuration",
+        content: 'The "assistant config" CLI command is available...',
+      },
+    ]);
+
+    const result = await injectMemoryV2Block({
+      database: db,
+      conversationId: "conv-1",
+      currentTurn: 1,
+      userMessage: "Help me",
+      assistantMessage: "",
+      nowText: "Now",
+      messageId: "msg-1",
+      config: makeConfig(),
+    });
+
+    expect(new Set(result.toInject)).toEqual(
+      new Set([
+        "alice-vscode",
+        "skills/example-skill-a",
+        "cli-commands/config",
+      ]),
+    );
+    const conceptIdx = result.block!.indexOf(
+      "# memory/concepts/alice-vscode.md",
+    );
+    const skillsIdx = result.block!.indexOf("### Skills You Can Use");
+    const cliIdx = result.block!.indexOf("### CLI Commands You Can Use");
+    expect(conceptIdx).toBeGreaterThan(-1);
+    expect(skillsIdx).toBeGreaterThan(conceptIdx);
+    expect(cliIdx).toBeGreaterThan(skillsIdx);
+  });
+
+  test("cli-command slugs whose entry is missing from the cache are dropped silently", async () => {
+    stageTurn([{ slug: "cli-commands/missing-command", denseScore: 0.9 }]);
+
+    const result = await injectMemoryV2Block({
+      database: db,
+      conversationId: "conv-1",
+      currentTurn: 1,
+      userMessage: "anything",
+      assistantMessage: "",
+      nowText: "Now",
+      messageId: "msg-1",
+      config: makeConfig(),
+    });
+
+    expect(result.toInject).toEqual([]);
+    expect(result.block).toBeNull();
+
+    const persisted = await hydrate(db, "conv-1");
+    expect(persisted!.everInjected).toEqual([]);
+  });
+
+  test("cli-commands participate in everInjected so they dedupe across turns", async () => {
+    const entry = {
+      id: "config",
+      description: "Manage configuration",
+      content: 'The "assistant config" CLI command is available...',
+    };
+    stageTurn([{ slug: "cli-commands/config", denseScore: 0.9 }]);
+    stageCliCommands([entry]);
+    const result1 = await injectMemoryV2Block({
+      database: db,
+      conversationId: "conv-1",
+      currentTurn: 1,
+      userMessage: "config",
+      assistantMessage: "",
+      nowText: "Now",
+      messageId: "msg-1",
+      config: makeConfig(),
+    });
+    expect(result1.toInject).toEqual(["cli-commands/config"]);
+    expect(result1.block).toContain("### CLI Commands You Can Use");
+
+    stageTurn([{ slug: "cli-commands/config", denseScore: 0.9 }]);
+    stageCliCommands([entry]);
+    const result2 = await injectMemoryV2Block({
+      database: db,
+      conversationId: "conv-1",
+      currentTurn: 2,
+      userMessage: "more config",
+      assistantMessage: "ok",
+      nowText: "Now",
+      messageId: "msg-2",
+      config: makeConfig(),
+    });
+    expect(result2.toInject).toEqual([]);
+    expect(result2.block).toBeNull();
+
+    const persisted = await hydrate(db, "conv-1");
+    expect(persisted!.everInjected).toEqual([
+      { slug: "cli-commands/config", turn: 1 },
+    ]);
+  });
+
   test("context-load mode renders topNow even when every slug was previously injected", async () => {
     // Turn 1 (per-turn): seed alice as injected.
     stageTurn([{ slug: "alice-vscode", denseScore: 0.9 }]);
@@ -1679,6 +1868,56 @@ describe("injectMemoryV2Block", () => {
       expect(row.concepts).toEqual([]);
     });
 
+    test("flag-on: router-failure path swallows a save() error and returns block:null instead of throwing", async () => {
+      // PR 30176 refactored router-failure handling to delegate to
+      // `finalizeInjection`. That regressed the prior inline log-and-continue
+      // semantics on the router-failure path: a transient SQLite write
+      // throwing during the stub-state save now aborted the whole turn
+      // because `finalizeInjection`'s try/catch re-threw caughtErr at the end.
+      //
+      // This test stages exactly that scenario — router returns
+      // `failureReason: api_error` AND `save()` throws — and asserts the
+      // turn completes with `{ block: null, toInject: [] }` rather than
+      // propagating the SQLite error to `prepareMemory`.
+      routerState.nextResult = {
+        selectedSlugs: [],
+        failureReason: "api_error",
+      };
+      activationStoreState.saveShouldThrow = true;
+
+      let threw: unknown = undefined;
+      let result: Awaited<ReturnType<typeof injectMemoryV2Block>> | undefined;
+      try {
+        result = await injectMemoryV2Block({
+          database: db,
+          conversationId: "conv-router-fail-save-throws",
+          currentTurn: 5,
+          userMessage: "anything",
+          assistantMessage: "ok",
+          nowText: "Now",
+          messageId: "msg-fail-save",
+          config: makeConfig({ router: { enabled: true } }),
+        });
+      } catch (err) {
+        threw = err;
+      }
+
+      expect(threw).toBeUndefined();
+      expect(result).toBeDefined();
+      expect(result!.block).toBeNull();
+      expect(result!.toInject).toEqual([]);
+
+      // Telemetry still flushes with `mode: "errored"` so the failure stays
+      // observable — the same row the inline pre-refactor path emitted.
+      expect(telemetryState.recordCalls.length).toBe(1);
+      const row = telemetryState.recordCalls[0] as {
+        mode: string;
+        concepts: unknown[];
+      };
+      expect(row.mode).toBe("errored");
+      expect(row.concepts).toEqual([]);
+    });
+
     test("flag-on: router abstention (empty selectedSlugs, no failure) writes mode:`router` row with no injected pages", async () => {
       routerState.nextResult = {
         selectedSlugs: [],
@@ -1904,5 +2143,43 @@ describe("injectMemoryV2Block", () => {
       const row = telemetryState.recordCalls[0] as { mode: string };
       expect(row.mode).toBe("per-turn");
     });
+
+    test("flag-on + mode='context-load': router runs (everInjected was cleared by onCompacted so dedupe is a no-op; abstention is accepted as the trade-off)", async () => {
+      // Context-load is the full top-K bootstrap fired after compaction or
+      // a fresh conversation reload. The earlier worry about the router's
+      // `everInjected` dedupe filtering out post-compaction restorations
+      // doesn't apply: `ConversationGraphMemory.onCompacted` calls
+      // `evictCompactedTurnsV2` which empties the list before this code
+      // runs. Router abstention here means no v2 pages this turn — that's
+      // preferable to letting the activation graph pick something arbitrary.
+      routerState.nextResult = {
+        selectedSlugs: ["alice-vscode"],
+        failureReason: null,
+      };
+
+      const result = await injectMemoryV2Block({
+        database: db,
+        conversationId: "conv-context-load-router-on",
+        currentTurn: 1,
+        userMessage: "Tell me about Alice",
+        assistantMessage: "",
+        nowText: "Now",
+        messageId: "msg-1",
+        mode: "context-load",
+        config: makeConfig({ router: { enabled: true } }),
+      });
+
+      // Router was called on context-load too.
+      expect(routerState.callCount).toBe(1);
+
+      // Router's picks were rendered.
+      expect(result.toInject).toEqual(["alice-vscode"]);
+      expect(result.block).toContain("# memory/concepts/alice-vscode.md");
+
+      // Telemetry row reflects the router mode, not the activation mode.
+      expect(telemetryState.recordCalls.length).toBe(1);
+      const row = telemetryState.recordCalls[0] as { mode: string };
+      expect(row.mode).toBe("router");
+    });
   });
 });

package/src/memory/v2/__tests__/migration.test.ts

@@ -754,6 +754,93 @@ describe("runMemoryV2Migration", () => {
     expect(body).toContain("second body");
   });
 
+  test("force=true cleanly strips the prior migration block from essentials.md", async () => {
+    insertNode(database, {
+      content: "Alice prefers VS Code.",
+      significance: 0.95,
+    });
+    await runMemoryV2Migration({
+      workspaceDir,
+      database,
+      provider: buildStubProvider("body"),
+    });
+
+    const essentialsPath = join(workspaceDir, "memory", "essentials.md");
+    const afterFirst = readFileSync(essentialsPath, "utf-8");
+    expect(afterFirst).toContain("<!-- migration:v1-to-v2 -->");
+    expect(afterFirst).toContain("<!-- /migration:v1-to-v2 -->");
+
+    await runMemoryV2Migration({
+      workspaceDir,
+      database,
+      provider: buildStubProvider("body"),
+      force: true,
+    });
+
+    const afterRerun = readFileSync(essentialsPath, "utf-8");
+    // Exactly one migration block — no leftover/duplicated markers.
+    expect(afterRerun.match(/<!-- migration:v1-to-v2 -->/g)?.length ?? 0).toBe(
+      1,
+    );
+    expect(
+      afterRerun.match(/<!-- \/migration:v1-to-v2 -->/g)?.length ?? 0,
+    ).toBe(1);
+  });
+
+  test("force=true preserves user-appended content after the migration block", async () => {
+    insertNode(database, {
+      content: "Alice prefers VS Code.",
+      significance: 0.95,
+    });
+    await runMemoryV2Migration({
+      workspaceDir,
+      database,
+      provider: buildStubProvider("body"),
+    });
+
+    const essentialsPath = join(workspaceDir, "memory", "essentials.md");
+    const beforeAppend = readFileSync(essentialsPath, "utf-8");
+    const userAppended = "\nUser added this after the migration ran.\n";
+    writeFileSync(essentialsPath, beforeAppend + userAppended, "utf-8");
+
+    await runMemoryV2Migration({
+      workspaceDir,
+      database,
+      provider: buildStubProvider("body"),
+      force: true,
+    });
+
+    const after = readFileSync(essentialsPath, "utf-8");
+    expect(after).toContain("User added this after the migration ran.");
+    // And exactly one migration envelope remains.
+    expect(after.match(/<!-- migration:v1-to-v2 -->/g)?.length ?? 0).toBe(1);
+    expect(after.match(/<!-- \/migration:v1-to-v2 -->/g)?.length ?? 0).toBe(1);
+  });
+
+  test("force=true on legacy (close-marker-less) file strips only up to the next blank line", async () => {
+    // Simulate a file written by the prior migration format: opening marker
+    // with no closing sentinel, with user-appended content separated by a
+    // blank line. The strip should preserve the user content.
+    insertNode(database, { content: "Alice prefers VS Code." });
+    const essentialsPath = join(workspaceDir, "memory", "essentials.md");
+    writeFileSync(
+      essentialsPath,
+      "<!-- migration:v1-to-v2 -->\nlegacy migrated line\n\nUser-appended legacy note.\n",
+      "utf-8",
+    );
+
+    await runMemoryV2Migration({
+      workspaceDir,
+      database,
+      provider: buildStubProvider("body"),
+      force: true,
+    });
+
+    const after = readFileSync(essentialsPath, "utf-8");
+    expect(after).toContain("User-appended legacy note.");
+    expect(after).not.toContain("legacy migrated line");
+  });
+
   test("clearing the sentinel allows a non-force re-run", async () => {
     insertNode(database, { content: "fact" });
     const provider = buildStubProvider("body");

package/src/memory/v2/__tests__/page-index.test.ts

@@ -245,6 +245,89 @@ describe("getPageIndex", () => {
     const idx = await getPageIndex(workspaceDir);
     expect(idx.bySlug.get("alice")?.summary.length).toBe(200);
   });
+
+  test("collapses embedded newlines in frontmatter.summary to single spaces", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("alice", { summary: "First line.\nSecond line.\nThird line." }),
+    );
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("alice")?.summary).toBe(
+      "First line. Second line. Third line.",
+    );
+  });
+
+  test("collapses embedded newlines and runs of whitespace in body fallback", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("alice", {
+        body: "  Body  with\n\nmultiple\tlines\n  and   spaces.  ",
+      }),
+    );
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("alice")?.summary).toBe(
+      "Body with multiple lines and spaces.",
+    );
+  });
+
+  test("normalizes skill-entry content with embedded newlines", async () => {
+    skillState.entries = [
+      { id: "browser", content: "Drive a browser.\nSupports multiple tabs." },
+    ];
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("skills/browser")?.summary).toBe(
+      "Drive a browser. Supports multiple tabs.",
+    );
+  });
+
+  test("renders a single line per entry even when summaries contain newlines", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("alice", { summary: "line one\nline two" }),
+    );
+    const idx = await getPageIndex(workspaceDir);
+    // Exactly one trailing newline — the entry itself must not split.
+    expect(idx.rendered.split("\n").filter(Boolean).length).toBe(1);
+  });
+
+  test("drops a user concept page whose slug collides with a seeded skill entry", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("skills/browser", {
+        summary: "User-authored page that shadows the skill.",
+      }),
+    );
+    skillState.entries = [{ id: "browser", content: "Seeded skill content." }];
+
+    const idx = await getPageIndex(workspaceDir);
+    // Only the skill entry survives under skills/browser.
+    expect(idx.entries.filter((e) => e.slug === "skills/browser").length).toBe(
+      1,
+    );
+    expect(idx.bySlug.get("skills/browser")?.summary).toBe(
+      "Seeded skill content.",
+    );
+  });
+
+  test("collision dedupe leaves non-colliding pages and skills intact", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "Alice" }));
+    await writePage(
+      workspaceDir,
+      makePage("skills/browser", { summary: "Shadow page." }),
+    );
+    skillState.entries = [
+      { id: "browser", content: "Seeded browser." },
+      { id: "calendar", content: "Seeded calendar." },
+    ];
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.entries.map((e) => e.slug)).toEqual([
+      "alice",
+      "skills/browser",
+      "skills/calendar",
+    ]);
+    expect(idx.bySlug.get("skills/browser")?.summary).toBe("Seeded browser.");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/memory/v2/__tests__/prompts-router.test.ts

@@ -123,6 +123,39 @@ describe("renderRouterPrompt — page index handling", () => {
   });
 });
 
+describe("renderRouterPrompt — replacement-pattern specials", () => {
+  // String.prototype.replaceAll interprets `$&`, `$'`, `` $` ``, `$$`, and
+  // `$n` in the replacement string as backreferences. LLM-generated page
+  // index content can contain literal `$` runs, so the substituter must
+  // pass values through unchanged.
+  const SPECIALS = "$& and $' and $` and $$ and $1";
+
+  test.each([
+    [
+      "pageIndexBlock",
+      { assistantName: "Aria", userName: "Alice", pageIndexBlock: SPECIALS },
+    ],
+    [
+      "assistantName",
+      {
+        assistantName: SPECIALS,
+        userName: "Alice",
+        pageIndexBlock: SAMPLE_INDEX,
+      },
+    ],
+    [
+      "userName",
+      {
+        assistantName: "Aria",
+        userName: SPECIALS,
+        pageIndexBlock: SAMPLE_INDEX,
+      },
+    ],
+  ])("renders %s with $ specials verbatim", (_, opts) => {
+    expect(renderRouterPrompt(opts)).toContain(SPECIALS);
+  });
+});
+
 describe("renderRouterPrompt — determinism & snapshot stability", () => {
   test("returns the same string for the same inputs", () => {
     const opts = {
@@ -196,7 +229,7 @@ describe("resolveRouterPrompt — override path", () => {
   };
 
   test("null overridePath returns the bundled prompt verbatim", () => {
-    expect(resolveRouterPrompt(null, STD_OPTS)).toEqual(
+    expect(resolveRouterPrompt(null, tmpDir, STD_OPTS)).toEqual(
       renderRouterPrompt(STD_OPTS),
     );
   });
@@ -209,16 +242,35 @@ describe("resolveRouterPrompt — override path", () => {
       "utf-8",
     );
 
-    const out = resolveRouterPrompt(overridePath, STD_OPTS);
+    const out = resolveRouterPrompt(overridePath, tmpDir, STD_OPTS);
     expect(out).toContain("Hi Aria, you are routing for Alice.");
     expect(out).toContain(SAMPLE_INDEX);
     expect(out).not.toContain("{{ASSISTANT_NAME}}");
     expect(out).not.toContain("{{PAGE_INDEX}}");
   });
 
+  test("relative override path is resolved under the passed workspaceDir, not the default workspace", () => {
+    // Write the override into the per-test temp dir, which acts as a
+    // non-default workspace. The configured path is purely relative so the
+    // loader must resolve it against the supplied workspaceDir — if it
+    // resolved against the process-wide default workspace instead, the file
+    // wouldn't be found and the bundled prompt would be returned.
+    const relativeName = "router-override.md";
+    writeFileSync(
+      join(tmpDir, relativeName),
+      "Routed via {{ASSISTANT_NAME}} for {{USER_NAME}} :: {{PAGE_INDEX}}",
+      "utf-8",
+    );
+
+    const out = resolveRouterPrompt(relativeName, tmpDir, STD_OPTS);
+    expect(out).toContain("Routed via Aria for Alice");
+    expect(out).toContain(SAMPLE_INDEX);
+    expect(out).not.toEqual(renderRouterPrompt(STD_OPTS));
+  });
+
   test("missing override file falls back to bundled prompt", () => {
     const overridePath = join(tmpDir, "does-not-exist.md");
-    expect(resolveRouterPrompt(overridePath, STD_OPTS)).toEqual(
+    expect(resolveRouterPrompt(overridePath, tmpDir, STD_OPTS)).toEqual(
       renderRouterPrompt(STD_OPTS),
     );
   });
@@ -226,7 +278,7 @@ describe("resolveRouterPrompt — override path", () => {
   test("empty override file falls back to bundled prompt", () => {
     const overridePath = join(tmpDir, "empty.md");
     writeFileSync(overridePath, "   \n\t\n", "utf-8");
-    expect(resolveRouterPrompt(overridePath, STD_OPTS)).toEqual(
+    expect(resolveRouterPrompt(overridePath, tmpDir, STD_OPTS)).toEqual(
       renderRouterPrompt(STD_OPTS),
     );
   });
@@ -234,7 +286,7 @@ describe("resolveRouterPrompt — override path", () => {
   test("override that is a directory falls back to bundled prompt", () => {
     // Pass the temp directory itself as the override path — lstat sees a
     // directory, not a regular file, so the loader bails to bundled.
-    expect(resolveRouterPrompt(tmpDir, STD_OPTS)).toEqual(
+    expect(resolveRouterPrompt(tmpDir, tmpDir, STD_OPTS)).toEqual(
       renderRouterPrompt(STD_OPTS),
     );
   });
@@ -247,7 +299,7 @@ describe("resolveRouterPrompt — override path", () => {
       "utf-8",
     );
 
-    const out = resolveRouterPrompt(overridePath, {
+    const out = resolveRouterPrompt(overridePath, tmpDir, {
       assistantName: null,
       userName: null,
       pageIndexBlock: "",