@frockbot/plugin-flock 0.3.10 → 0.3.12

package/src/client/index.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import type { ClientPluginContext } from "@frockbot/client-core";
 import type { FrockBotWebData } from "@frockbot/plugin-shell/shared";
-import { ref, type Ref } from "vue";
+import { nextTick, ref, type Ref } from "vue";
 import { randomSheepRecipeV1 } from "../shared.js";
 import { flockClientPlugin } from "./index.js";
 import { pendingCreateKey, pendingSheepKey } from "./pending-create.js";
@@ -281,7 +281,8 @@ describe("Flock client reconciliation", () => {
 
     await state.value.load();
 
-    expect(state.value.error).toBe("Directory changed");
+    // The sidebar says what failed, not what the deployment called it.
+    expect(state.value.error).toBe("Couldn't load your Bots.");
     expect(storage.has(pendingCreateKey("user-a"))).toBe(false);
   });
 
@@ -481,6 +482,7 @@ describe("Flock client reconciliation", () => {
       return Promise.reject(new Error(`unexpected request: ${path}`));
     });
     const selected: string[] = [];
+    const forgotten: (string | undefined)[] = [];
     state.value.bindShell(
       ref({
         activeBotId: "alpha",
@@ -488,6 +490,11 @@ describe("Flock client reconciliation", () => {
           selected.push(botId);
           return Promise.resolve();
         },
+        transcripts: {
+          rememberViewport: () => undefined,
+          viewportFor: () => undefined,
+          forget: (botId?: string) => forgotten.push(botId),
+        },
       }) as unknown as Ref<FrockBotWebData>,
     );
     state.value.openArchive("alpha");
@@ -496,6 +503,9 @@ describe("Flock client reconciliation", () => {
     expect(state.value.lifecycles.alpha).toBe("archived");
     expect(selected.at(-1)).toBe("beta");
     expect(new URL(location.href).searchParams.get("bot")).toBe("beta");
+    // The archived Bot's held transcript goes with it, so restoring it later
+    // reads from the Bot rather than redrawing what the cache still had.
+    expect(forgotten).toEqual(["alpha"]);
   });
 
   test("reconciles a lost sheep response and clears the exact pending command", async () => {
@@ -532,3 +542,88 @@ describe("Flock client reconciliation", () => {
     expect(storage.has(pendingSheepKey("user-a", "alpha"))).toBe(false);
   });
 });
+
+describe("Flock sidebar rows follow the transcript", () => {
+  test("a settled Turn updates the row without waiting for the poll", async () => {
+    installStorage();
+    const reads: string[] = [];
+    let reply: string | undefined;
+    const state = mount((path) => {
+      if (path !== "/api/bots/unread")
+        return Promise.reject(new Error(`unexpected request: ${path}`));
+      reads.push(path);
+      return Promise.resolve({
+        schemaVersion: 1,
+        unread: [
+          {
+            schemaVersion: 1,
+            botId: "alpha",
+            count: 0,
+            capped: false,
+            unread: false,
+            manuallyUnread: false,
+            ...(reply === undefined
+              ? {}
+              : {
+                  lastMessage: {
+                    schemaVersion: 1,
+                    text: reply,
+                    at: "2026-08-31T00:00:01.000Z",
+                    role: "assistant",
+                  },
+                }),
+          },
+        ],
+      });
+    });
+    const shell = ref({
+      activeBotId: "alpha",
+      activeRunId: "run-1",
+      messages: [
+        {
+          id: "m1",
+          runId: "run-1",
+          role: "user",
+          text: "hello",
+          status: "completed",
+        },
+      ],
+    } as unknown as FrockBotWebData);
+    state.value.bindShell(shell as unknown as Ref<FrockBotWebData>);
+    // Binding a Shell is not itself a beat: nothing has settled, so nothing is
+    // re-read.
+    await nextTick();
+    expect(reads).toHaveLength(0);
+    expect(state.value.unread.alpha).toBeUndefined();
+
+    // The Turn settles: its reply is in the transcript, no run is in flight.
+    reply = "Ollama reply";
+    shell.value = {
+      ...shell.value,
+      activeRunId: undefined,
+      messages: [
+        ...shell.value.messages,
+        {
+          id: "m2",
+          runId: "run-1",
+          role: "assistant",
+          text: reply,
+          status: "completed",
+        },
+      ],
+    } as unknown as FrockBotWebData;
+    await nextTick();
+    // Draining the read the watcher started. A rendered frame does this on its
+    // own; the claim under test is that no 15-second poll was involved.
+    await Promise.resolve();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(reads).toHaveLength(1);
+    expect(state.value.unread.alpha?.lastMessage).toMatchObject({
+      text: "Ollama reply",
+      at: "2026-08-31T00:00:01.000Z",
+      role: "assistant",
+    });
+  });
+});

package/src/client/index.ts

@@ -25,7 +25,18 @@ import {
   decodeBotUnreadDirectoryViewV1,
   decodeBotUnreadReceiptV1,
 } from "@frockbot/plugin-shell/unread";
+import {
+  isBotFocusedV1,
+  readViewerFocusV1,
+  shouldNotifyForBotV1,
+  suppressUnreadWhileFocusedV1,
+} from "@frockbot/plugin-shell/focus";
 import { showClientNotificationV1 } from "@frockbot/plugin-shell/client/notify";
+import {
+  claimNotificationDeliveryV1,
+  deliveredNotificationKeyV1,
+  releaseNotificationDeliveryV1,
+} from "./delivered-notifications.js";
 import {
   clearPendingCreate,
   clearPendingSheep,
@@ -39,6 +50,10 @@ import { flockWebDataKey, type FlockWebData } from "./state.js";
 import "../../assets/layers.css";
 import "./styles.css";
 import { defineClientContribution } from "@frockbot/kernel-contracts/contributions";
+import {
+  clientFailureDetailV1,
+  presentClientFailureV1,
+} from "@frockbot/client-core";
 
 function slug(name: string): string {
   const base =
@@ -91,13 +106,52 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
     throw new Error("Flock hosted transport is unavailable");
   const request = ctx.transport.hostedRequest.bind(ctx.transport);
   let shell: Ref<FrockBotWebData> | undefined;
-  /** Stops the watcher that keeps a renamed Bot's sidebar row in step. */
+  /** Stops the watcher that keeps an edited Bot's sidebar row in step. */
   let stopNameWatch: (() => void) | undefined;
+  /** Stops the watcher that refreshes the row on the transcript's own beat. */
+  let stopTranscriptWatch: (() => void) | undefined;
+  /** Stops the visibility/focus listeners that re-decide what is being read. */
+  let stopFocusListeners: (() => void) | undefined;
   let authenticatedUserId: string | undefined;
   let loadGeneration = 0;
   let selectionGeneration = 0;
   /** Intents already shown by this page, so a poll cannot show one twice. */
   const deliveredNotifications = new Set<string>();
+  /** The refresh currently in flight, so overlapping beats collapse into one. */
+  let unreadRefresh: Promise<void> | undefined;
+  /** A beat that arrived while one was in flight, replayed once it finishes. */
+  let unreadRefreshQueued = false;
+
+  /**
+   * One unread read at a time, with at most one more behind it.
+   *
+   * A Turn produces several beats — its line appears, it streams, it settles —
+   * and each is a reason to re-read the row. Firing a request per beat would
+   * make the sidebar noisier than the transcript it is following, and
+   * out-of-order replies could put an older row back. Collapsing to one
+   * in-flight read plus one pending replay keeps the last beat authoritative.
+   * A failure is a refresh that did not happen: the poll tries again.
+   */
+  function refreshUnreadCoalesced(): Promise<void> {
+    if (unreadRefresh) {
+      unreadRefreshQueued = true;
+      return unreadRefresh;
+    }
+    unreadRefresh = (async () => {
+      try {
+        await state.value.refreshUnread();
+      } catch {
+        // A refresh is never authority; the poll retries and nothing is lost.
+      } finally {
+        unreadRefresh = undefined;
+      }
+      if (unreadRefreshQueued) {
+        unreadRefreshQueued = false;
+        await refreshUnreadCoalesced();
+      }
+    })();
+    return unreadRefresh;
+  }
 
   async function requireAuthenticatedUserId(): Promise<string> {
     if (!ctx.transport.readAuthenticatedUserId)
@@ -120,24 +174,89 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
     draftSheep: randomSheepRecipeV1(),
     bindShell(value) {
       shell = value;
-      // A rename is saved on the Bot's own settings, and the sidebar reads a
-      // directory it loaded once — so the row kept the old name until the page
-      // was reloaded. The row follows the settings the Shell is already
-      // holding rather than waiting for a second read of the directory.
+      // A rename — or a pin — is saved on the Bot's own settings, and the
+      // sidebar reads a directory it loaded once, so the row kept the old name
+      // until the page was reloaded. The row follows the settings the Shell is
+      // already holding rather than waiting for a second read of the directory.
       stopNameWatch?.();
       stopNameWatch = watch(
-        () => value.value.botSettings?.profile.name,
-        (name) => {
-          const botId = value.value.botSettings?.botId;
-          if (!botId || !name) return;
+        () => {
+          const profile = value.value.botSettings?.profile;
+          return `${profile?.name ?? ""}\u0000${profile?.pinnedAt ?? ""}`;
+        },
+        () => {
+          const settings = value.value.botSettings;
+          const botId = settings?.botId;
+          if (!botId || !settings?.profile.name) return;
           const profile = state.value.profiles[botId];
-          if (!profile || profile.name === name) return;
+          if (!profile) return;
+          const pinnedAt = settings.profile.pinnedAt;
+          if (
+            profile.name === settings.profile.name &&
+            profile.pinnedAt === pinnedAt
+          )
+            return;
+          // Unpinning removes the field rather than blanking it, so the
+          // identity the sidebar reads keeps the shape its decoder produces.
+          const { pinnedAt: _previous, ...rest } = profile;
           state.value.profiles = {
             ...state.value.profiles,
-            [botId]: { ...profile, name },
+            [botId]: {
+              ...rest,
+              name: settings.profile.name,
+              ...(pinnedAt === undefined ? {} : { pinnedAt }),
+            },
           };
         },
       );
+      // The row and the transcript are two renderings of the same Turn, so
+      // they have to move together. The poll below is a floor — a Bot nobody
+      // is looking at still gets its badge within a tick — but the open Bot's
+      // own conversation already knows the instant a line lands or a Turn
+      // settles, and a row that reads "No messages yet" over a reply the User
+      // is looking at is the poll's latency made visible. The signal is
+      // per-line, never per-token: the newest line's identity and status, the
+      // number of lines, and whether a Turn is in flight.
+      stopTranscriptWatch?.();
+      stopTranscriptWatch = watch(
+        () => {
+          const web = value.value;
+          // A host that has not projected a transcript yet — the first paint,
+          // and every test double — contributes no beat rather than throwing.
+          const messages = web.messages ?? [];
+          const last = messages[messages.length - 1];
+          return [
+            web.activeBotId ?? "",
+            web.activeRunId ?? "",
+            messages.length,
+            last?.id ?? "",
+            last?.status ?? "",
+          ].join(":");
+        },
+        () => {
+          void refreshUnreadCoalesced();
+        },
+      );
+      // Coming back to the window is the other moment the answer changes.
+      // Nothing about the transcript moved — the Bot replied while the tab was
+      // hidden, and both the badge and the notification were right to appear —
+      // but the User is now looking at that very chat, so the badge has to go
+      // without waiting for a poll. The same beat covers looking away: the row
+      // the rule was suppressing becomes an honest badge again.
+      if (typeof document !== "undefined" && !stopFocusListeners) {
+        const refresh = (): void => {
+          if (!state.value.directory.bots.length) return;
+          void refreshUnreadCoalesced();
+        };
+        document.addEventListener("visibilitychange", refresh);
+        window.addEventListener("focus", refresh);
+        window.addEventListener("blur", refresh);
+        stopFocusListeners = () => {
+          document.removeEventListener("visibilitychange", refresh);
+          window.removeEventListener("focus", refresh);
+          window.removeEventListener("blur", refresh);
+        };
+      }
     },
     async load() {
       const generation = ++loadGeneration;
@@ -155,6 +274,7 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
         authenticatedUserId = userId;
         state.value.directory = directory;
         state.value.loaded = true;
+        if (shell) shell.value.botsUnavailable = false;
         state.value.lifecycles = Object.fromEntries(
           lifecycleDirectory.lifecycles.map((item) => [
             item.botId,
@@ -246,8 +366,14 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
         else if (!selected && state.value.directory.bots.length === 0)
           state.value.openCreate();
       } catch (error) {
-        state.value.error =
-          error instanceof Error ? error.message : "Could not load your flock";
+        // The list already on screen is the last thing known to be true, so a
+        // failed refresh leaves it alone and says so instead. A transport
+        // failure that emptied the sidebar would read as data loss.
+        state.value.error = presentClientFailureV1(error, "load your Bots");
+        console.debug("flock load failed", clientFailureDetailV1(error));
+        // Tell the workspace the list is unknown, so it stops offering the
+        // first-run empty state to a User who may already have Bots.
+        if (shell && !state.value.loaded) shell.value.botsUnavailable = true;
       } finally {
         if (generation === loadGeneration) state.value.loading = false;
       }
@@ -256,22 +382,31 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
       const directory = decodeBotUnreadDirectoryViewV1(
         await request("/api/bots/unread"),
       );
-      state.value.unread = Object.fromEntries(
-        directory.unread.map((view) => [view.botId, view]),
-      );
       // A Turn that settles in the conversation the User is looking at has
       // been read by the time it arrives, so the badge that counted it is
-      // wrong the instant it appears. Reading up to it is still the explicit
-      // authenticated command; what the poll refreshed is only which cursor it
-      // names. Every other Bot's badge is left exactly as the fan-out said.
-      const openBotId = shell?.value.activeBotId;
+      // wrong the instant it appears — and painting it for the beat before the
+      // receipt lands is exactly the flicker the rule forbids. The row for a
+      // focused Bot therefore renders no count at all, whatever the fan-out
+      // says. Every other Bot's badge is left exactly as it came.
+      const focus = readViewerFocusV1(shell?.value.activeBotId);
+      state.value.unread = Object.fromEntries(
+        directory.unread.map((view) => [
+          view.botId,
+          isBotFocusedV1(focus, view.botId)
+            ? suppressUnreadWhileFocusedV1(view)
+            : view,
+        ]),
+      );
+      // Suppression is what the row shows; the read receipt is what makes it
+      // stay shown — on the next reload, and in the other tab. It is still the
+      // explicit authenticated command, never a side effect of the read.
+      const openBotId = focus.activeBotId;
       if (
         openBotId &&
-        (state.value.unread[openBotId]?.count ?? 0) > 0 &&
-        !state.value.unread[openBotId]?.manuallyUnread &&
-        typeof document !== "undefined" &&
-        document.visibilityState === "visible" &&
-        document.hasFocus()
+        isBotFocusedV1(focus, openBotId) &&
+        (directory.unread.find((view) => view.botId === openBotId)?.count ??
+          0) > 0 &&
+        !state.value.unread[openBotId]?.manuallyUnread
       ) {
         try {
           await state.value.markRead(openBotId);
@@ -281,7 +416,27 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
       }
     },
     async markRead(botId) {
-      const cursor = state.value.unread[botId]?.lastActivityCursor;
+      let cursor = state.value.unread[botId]?.lastActivityCursor;
+      // Only when this page has never seen the Bot's row at all. A row that is
+      // present without a cursor is a Bot nothing has ever settled on — a Bot
+      // just created, most often — and asking again would put a round trip in
+      // front of every first open to learn what it already knows.
+      if (!cursor && !state.value.unread[botId]) {
+        // Opening a chat has to clear its badge even when this page has not
+        // read the fan-out yet: the first click after a reload. One read names
+        // the cursor; without it the badge sat there until the next poll.
+        try {
+          const directory = decodeBotUnreadDirectoryViewV1(
+            await request("/api/bots/unread"),
+          );
+          for (const view of directory.unread) {
+            state.value.unread[view.botId] ??= view;
+            if (view.botId === botId) cursor = view.lastActivityCursor;
+          }
+        } catch {
+          // Fall through: with no cursor there is nothing to read up to.
+        }
+      }
       // Nothing has ever settled on this Bot: there is no cursor to read up to.
       if (!cursor) return;
       const receipt = decodeBotUnreadReceiptV1(
@@ -330,13 +485,17 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
       if (generation !== selectionGeneration) return;
       if (!shell) throw new Error("Shell selection is unavailable");
       await shell.value.selectBot(botId);
-      // Selecting a thread while looking at it is what "read" means. A
-      // background poll that refreshed the same runs must never do this.
-      if (
-        generation === selectionGeneration &&
-        typeof document !== "undefined" &&
-        document.visibilityState === "visible"
-      ) {
+      // Selecting a thread while looking at it is what "read" means, and it
+      // is the whole of "opening a chat clears its badge". Focus is not
+      // required — opening is the User's own act, and a window that has just
+      // been clicked may not report focus yet — but a visible tab is: a page
+      // restoring `?bot=` in a background tab has not been read.
+      if (generation === selectionGeneration && readViewerFocusV1().visible) {
+        // The row clears now rather than on the next poll, so the badge never
+        // outlives the click. The receipt below is what makes it durable.
+        const view = state.value.unread[botId];
+        if (view)
+          state.value.unread[botId] = suppressUnreadWhileFocusedV1(view);
         try {
           await state.value.markRead(botId);
         } catch {
@@ -391,10 +550,13 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
         }
         state.value.overlay = undefined;
         state.value.lifecyclePending = undefined;
+        // An archived Bot's transcript is no longer something to open
+        // instantly: the next time it is read it is read from the Bot.
+        shell?.value.transcripts.forget(botId);
         await state.value.load();
       } catch (error) {
-        state.value.error =
-          error instanceof Error ? error.message : "Could not archive Bot";
+        state.value.error = presentClientFailureV1(error, "archive this Bot");
+        console.debug("bot archive failed", clientFailureDetailV1(error));
       }
     },
     async restore(botId) {
@@ -417,10 +579,11 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
           state.value.error = "Still restoring — this will finish shortly.";
           return;
         }
+        shell?.value.transcripts.forget(botId);
         await state.value.load();
       } catch (error) {
-        state.value.error =
-          error instanceof Error ? error.message : "Could not restore Bot";
+        state.value.error = presentClientFailureV1(error, "restore this Bot");
+        console.debug("bot restore failed", clientFailureDetailV1(error));
       }
     },
     async openEdit() {
@@ -460,10 +623,8 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
           );
           state.value.identities[botId] = identity;
         } catch (error) {
-          state.value.error =
-            error instanceof Error
-              ? error.message
-              : "Couldn't finish saving your last change.";
+          state.value.error = presentClientFailureV1(error, "load this sheep");
+          console.debug("sheep refresh failed", clientFailureDetailV1(error));
           return;
         }
       }
@@ -514,8 +675,8 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
       } catch (error) {
         if (isDefinitiveFlockFailure(error) && authenticatedUserId)
           clearPendingCreate(authenticatedUserId);
-        state.value.error =
-          error instanceof Error ? error.message : "Could not create Bot";
+        state.value.error = presentClientFailureV1(error, "create the Bot");
+        console.debug("bot creation failed", clientFailureDetailV1(error));
       }
     },
     async saveSheep() {
@@ -576,8 +737,8 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
             /* Keep the exact pending command when reconciliation is uncertain. */
           }
         }
-        state.value.error =
-          error instanceof Error ? error.message : "Could not save sheep";
+        state.value.error = presentClientFailureV1(error, "save the sheep");
+        console.debug("sheep save failed", clientFailureDetailV1(error));
       }
     },
   });
@@ -600,20 +761,41 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
           notificationId: intent.notificationId,
         }),
       );
+    const focus = readViewerFocusV1(shell?.value.activeBotId);
     for (const intent of directory.notifications) {
       // The open Bot's intents belong to the Shell: it projects the Turn into
-      // the conversation and acknowledges it there.
-      if (intent.botId === shell?.value.activeBotId) continue;
-      const key = `${intent.botId}:${intent.notificationId}`;
-      if (deliveredNotifications.has(key)) {
+      // the conversation, decides whether the tab was being looked at, and
+      // acknowledges it there. Deciding again here would be a second answer to
+      // the same question, and a second notification when they disagreed.
+      if (intent.botId === focus.activeBotId) continue;
+      // Every other Bot is out of focus by definition — the sentence this
+      // implements — so the intent is one notification, once.
+      if (!shouldNotifyForBotV1(focus, intent.botId)) continue;
+      const key = deliveredNotificationKeyV1(
+        intent.botId,
+        intent.notificationId,
+      );
+      if (deliveredNotifications.has(key)) continue;
+      // Claimed before it is shown, and claimed in storage every tab of this
+      // browser shares: the acknowledgement that finally closes the intent
+      // lands after the notification, and a second tab polling in that gap
+      // used to speak the same message twice.
+      if (!claimNotificationDeliveryV1(key)) {
+        deliveredNotifications.add(key);
         continue;
       }
+      deliveredNotifications.add(key);
       const delivery = await showClientNotificationV1({
         title: intent.title,
         body: intent.body,
       });
-      if (delivery === "unavailable") continue;
-      deliveredNotifications.add(key);
+      if (delivery === "unavailable") {
+        // Nothing was said, so nothing was spent: the intent stays pending and
+        // is spoken once the User grants permission.
+        deliveredNotifications.delete(key);
+        releaseNotificationDeliveryV1(key);
+        continue;
+      }
       await acknowledge(intent);
     }
   }
@@ -622,7 +804,7 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
     if (!state.value.directory.bots.length) return;
     void (async () => {
       try {
-        await state.value.refreshUnread();
+        await refreshUnreadCoalesced();
         await deliverBackgroundNotifications();
       } catch {
         // A poll is a refresh, not authority: the next tick tries again and
@@ -634,6 +816,8 @@ export const flockClientPlugin: ClientPlugin = (ctx) => {
   return [
     () => clearInterval(poll),
     () => stopNameWatch?.(),
+    () => stopTranscriptWatch?.(),
+    () => stopFocusListeners?.(),
     ctx.provide(flockWebDataKey, state),
     ctx.slot({
       slot: "frockbot.sidebar-bots",

package/src/client/sidebar.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { formatSidebarMessageTimeV1, groupSidebarBotsV1 } from "./sidebar.js";
+import {
+  formatSidebarMessageTimeV1,
+  groupSidebarBotsV1,
+  partitionPinnedSidebarBotsV1,
+} from "./sidebar.js";
 
 const bots = [
   { botId: "alpha" },
@@ -8,6 +12,48 @@ const bots = [
   { botId: "delta" },
 ];
 
+describe("pinned sidebar Bots", () => {
+  test("orders pinned Bots by pin time and leaves the rest in list order", () => {
+    expect(
+      partitionPinnedSidebarBotsV1(bots, {
+        alpha: { pinnedAt: "2026-09-02T09:00:00.000Z" },
+        beta: {},
+        gamma: { pinnedAt: "2026-08-30T09:00:00.000Z" },
+      }),
+    ).toEqual({
+      pinned: [{ botId: "gamma" }, { botId: "alpha" }],
+      rest: [{ botId: "beta" }, { botId: "delta" }],
+    });
+  });
+
+  test("a pinned Bot leaves the labelled groups entirely", () => {
+    const profiles: Record<string, { label?: string; pinnedAt?: string }> = {
+      alpha: { label: "Work", pinnedAt: "2026-09-02T09:00:00.000Z" },
+      beta: { label: "Work" },
+    };
+    const { pinned, rest } = partitionPinnedSidebarBotsV1(
+      bots.slice(0, 2),
+      profiles,
+    );
+    expect(pinned.map((bot) => bot.botId)).toEqual(["alpha"]);
+    expect(
+      groupSidebarBotsV1(rest, profiles).groups.map((group) => ({
+        label: group.label,
+        bots: group.bots.map((bot) => bot.botId),
+      })),
+    ).toEqual([{ label: "Work", bots: ["beta"] }]);
+  });
+
+  test("treats a blank pin instant as unpinned", () => {
+    expect(
+      partitionPinnedSidebarBotsV1(bots.slice(0, 2), {
+        alpha: { pinnedAt: "  " },
+        beta: {},
+      }).pinned,
+    ).toEqual([]);
+  });
+});
+
 describe("sidebar Bot groups", () => {
   test("renders one plain list until a visible Bot has a label", () => {
     expect(groupSidebarBotsV1(bots.slice(0, 2), {})).toEqual({

package/src/client/sidebar.ts

@@ -1,3 +1,40 @@
+export interface PinnedSidebarBotsV1<T> {
+  /** Pinned Bots, earliest pin first. Rendered as tiles above the list. */
+  pinned: T[];
+  /** Everything else, in the order it arrived. */
+  rest: T[];
+}
+
+/**
+ * Splits the pinned Bots out of the sidebar list. A pinned Bot is a tile at
+ * the top instead of a row below, never both, so the list this returns is what
+ * {@link groupSidebarBotsV1} then groups by label.
+ *
+ * Order is by pin time — earliest first — because the tile row is a place a
+ * User builds up over time and a Bot pinned today must not displace the one
+ * they pinned last month. Ties and unparseable instants keep list order.
+ */
+export function partitionPinnedSidebarBotsV1<T extends { botId: string }>(
+  bots: readonly T[],
+  profiles: Readonly<Record<string, { pinnedAt?: string } | undefined>>,
+): PinnedSidebarBotsV1<T> {
+  const pinned: Array<{ bot: T; at: number; index: number }> = [];
+  const rest: T[] = [];
+  for (const [index, bot] of bots.entries()) {
+    const pinnedAt = profiles[bot.botId]?.pinnedAt?.trim();
+    if (!pinnedAt) {
+      rest.push(bot);
+      continue;
+    }
+    const at = Date.parse(pinnedAt);
+    pinned.push({ bot, at: Number.isFinite(at) ? at : 0, index });
+  }
+  pinned.sort((left, right) =>
+    left.at === right.at ? left.index - right.index : left.at - right.at,
+  );
+  return { pinned: pinned.map((entry) => entry.bot), rest };
+}
+
 export interface SidebarBotGroupV1<T> {
   key: string;
   label: string;