Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

39.7 KB
Raw Blame
/**
 * How the chat sidebar groups Sessions (lib/session-grouping.ts): by Workspace, by time
 * bucket, and into the folders under each group.
 *
 * - A temporary Workspace (`…/workspaces/<dir>` of an Agent, or an empty path) is recognized
 *   on either path separator; near misses and nested directories are not.
 * - A group key is the trimmed path, or one shared sentinel for every temporary Workspace; a
 *   machine's directory keys under that machine and splits back into machine and path, while
 *   the server query carries the path only. A label is the path's last segment.
 * - Grouping by Workspace merges Agents on one path (newest Session first, newest group first),
 *   folds every temporary Workspace into one trailing group per machine, keeps one path on two
 *   machines apart, and keeps archived rows in their group.
 * - A Session's folder is decided by archived first, then its source: a person's conversation
 *   (`user`, or not yet classified) is active, every other source goes to Background;
 *   partitioning keeps the order inside each folder. A company Session, archived or not, is in
 *   no category and no part.
 * - The auto-opened "last conversation" is the most recently active person's conversation
 *   (ties by id), never an archived, a background (scheduled ones included) or a company one.
 * - A page fetched with one extra row reports whether the server has more, never showing it.
 * - Server counts sum per Workspace across Agents (recording which Agents hold each folder) and
 *   stay apart per machine; the newest stamp per group survives aggregation.
 * - Pinned items come first, each partition keeping its order; unknown pins are ignored.
 * - Title search is a case-insensitive substring match; a blank query matches everything and
 *   an untitled Session matches no non-blank query.
 * - Time buckets cut at 24 hours and 30 days on last activity, skewed stamps land newest and
 *   unreadable ones oldest, empty buckets are dropped, and bucket keys never collide with a
 *   path or an Agent id.
 * - Every counted Workspace becomes a group (empty when none of its rows loaded), placed by
 *   the newer of its stamp and its loaded rows, the temp group last; a count of zero forms none.
 * - The activity order is last activity, then id, both by code point — where a locale's
 *   collation would rank case or punctuation the other way, it does not follow it.
 * - A merged list's watermark is the most recent cursor among the streams with more; a stream
 *   with nothing read, or nothing left, bounds nothing. The cut keeps the rows at or above it
 *   and the open conversation wherever it falls; no watermark keeps every row.
 * - Property (seeded, 200 runs): over 1–4 streams paged by cursor, with live flips moving rows
 *   up (a loaded one in place, an unloaded one fetched), the cut list is always a prefix of the
 *   true order; a load only appends below it, and loading every stream with more shows at
 *   least a page more, or the rest.
 */
import { describe, expect, it } from "vitest";
import type { SessionCategoryCounts, SessionInfo, SessionSource } from "@adelie/server/api";
import type { ActivityKey, StreamPosition } from "../src/lib/session-grouping";
import {
  SIDEBAR_PAGE_SIZE,
  TEMP_WORKSPACE_GROUP_KEY,
  TIME_BUCKETS,
  TIME_FOLDERS_GROUP_KEY,
  aggregateWorkspaceCounts,
  aggregateWorkspaceLatest,
  activityCursorParam,
  activityWatermark,
  compareActivityDesc,
  completeWorkspaceGroups,
  cutAtWatermark,
  matchesSessionQuery,
  groupSessionsByTime,
  groupSessionsByWorkspace,
  isTempWorkspace,
  latestConversation,
  partitionSessions,
  pinnedFirst,
  sessionCategory,
  splitPage,
  timeBucketOf,
  timeGroupKey,
  totalCategoryCounts,
  workspaceGroupKey,
  workspaceGroupMachine,
  workspaceGroupPath,
  workspaceGroupQuery,
  workspaceLabel,
} from "../src/lib/session-grouping";

let seq = 0;
function session(
  workspace: string,
  createdAt: string,
  over: {
    sessionId?: string;
    agentId?: string;
    archived?: boolean;
    source?: SessionSource;
    lastActiveAt?: string;
  } = {},
): SessionInfo {
  seq += 1;
  return {
    sessionId: over.sessionId ?? `session-${seq}`,
    projectId: "proj",
    agentId: over.agentId ?? "default_agent",
    provider: "custom",
    modelId: "claude-4-8",
    workspace,
    approvalMode: "allow-all",
    sandbox: { mode: "danger-full-access", network: "open" },
    createdAt,
    lastActiveAt: over.lastActiveAt ?? createdAt,
    status: "idle",
    pendingApprovalCount: 0,
    pendingFollowUpCount: 0,
    hasTrace: false,
    archived: over.archived ?? false,
    ...(over.source !== undefined ? { source: over.source } : {}),
  };
}

const TEMP_A = "/data/proj/agents/default_agent/workspaces/tmp-1a2b3c4d";
const TEMP_B = "/data/proj/agents/agent_helper/workspaces/tmp-00ff00aa";
/** A machine's own id, as one mints for itself: 16 base64url characters. */
const MACHINE = "noeSE0FFHhNXl2J5";

describe("isTempWorkspace (temporary-workspace pattern from core's createTempWorkspace)", () => {
  it("matches <...>/workspaces/tmp-<8hex> with either path separator, and the empty path", () => {
    expect(isTempWorkspace(TEMP_A)).toBe(true);
    expect(isTempWorkspace("C:\\pg\\data\\proj\\agents\\a\\workspaces\\tmp-00ff00aa")).toBe(true);
    expect(isTempWorkspace("")).toBe(true);
    expect(isTempWorkspace("   ")).toBe(true);
  });

  it("matches any directory directly under an Agent's workspaces/ — the evaluation Skill's Test Workspaces", () => {
    expect(
      isTempWorkspace("/pg/data/proj/agents/a/workspaces/eval-example-benchmark-case-1-run-1"),
    ).toBe(true);
    expect(isTempWorkspace("C:\\pg\\data\\proj\\agents\\a\\workspaces\\run-7")).toBe(true);
    // A directory below one of them is not itself such a Workspace, and a workspaces/
    // directory that is not an Agent's is a user directory that just looks similar.
    expect(isTempWorkspace("/pg/data/proj/agents/a/workspaces/run-7/nested")).toBe(false);
    expect(isTempWorkspace("/srv/repo/workspaces/run-7")).toBe(false);
    expect(isTempWorkspace("/pg/data/proj/agents/a/workspaces")).toBe(false);
  });

  it("rejects named directories and near misses", () => {
    expect(isTempWorkspace("/srv/repo")).toBe(false);
    // tmp-<8hex> without a workspaces/ parent is a user directory that just looks similar
    expect(isTempWorkspace("/srv/tmp-1a2b3c4d")).toBe(false);
    // non-hex / wrong-length ids
    expect(isTempWorkspace("/x/workspaces/tmp-XYZWQPRS")).toBe(false);
    expect(isTempWorkspace("/x/workspaces/tmp-1a2b3c4")).toBe(false);
    expect(isTempWorkspace("/x/workspaces/tmp-1a2b3c4d5")).toBe(false);
    // a subdirectory below a temporary workspace is not itself the temporary workspace
    expect(isTempWorkspace(`${TEMP_A}/nested`)).toBe(false);
  });
});

describe("workspaceGroupKey / workspaceLabel", () => {
  it("named paths key by the (trimmed) path itself; temp and empty paths share the sentinel", () => {
    expect(workspaceGroupKey("/srv/repo")).toBe("/srv/repo");
    expect(workspaceGroupKey(" /srv/repo ")).toBe("/srv/repo");
    expect(workspaceGroupKey(TEMP_A)).toBe(TEMP_WORKSPACE_GROUP_KEY);
    expect(workspaceGroupKey("")).toBe(TEMP_WORKSPACE_GROUP_KEY);
  });

  it("a machine's directory keys under that machine, and this server keys as it always did", () => {
    // The same path on two machines is two different directories. Absence keeps meaning
    // "here", which is what every key already persisted in a browser was written as.
    expect(workspaceGroupKey("/srv/repo", MACHINE)).toBe(`${MACHINE}\u0000/srv/repo`);
    expect(workspaceGroupKey("/srv/repo", null)).toBe("/srv/repo");
    expect(workspaceGroupKey("/srv/repo", MACHINE)).not.toBe(workspaceGroupKey("/srv/repo"));
    expect(workspaceGroupKey(TEMP_A, MACHINE)).toBe(`${MACHINE}\u0000${TEMP_WORKSPACE_GROUP_KEY}`);
  });

  it("a key splits back into the machine that holds it and the workspace half", () => {
    expect(workspaceGroupMachine(workspaceGroupKey("/srv/repo", MACHINE))).toBe(MACHINE);
    expect(workspaceGroupMachine(workspaceGroupKey(TEMP_A, MACHINE))).toBe(MACHINE);
    expect(workspaceGroupMachine("/srv/repo")).toBeNull();
    expect(workspaceGroupMachine(TEMP_WORKSPACE_GROUP_KEY)).toBeNull();
    expect(workspaceGroupPath(workspaceGroupKey("/srv/repo", MACHINE))).toBe("/srv/repo");
    expect(workspaceGroupPath(workspaceGroupKey(TEMP_A, MACHINE))).toBe(TEMP_WORKSPACE_GROUP_KEY);
  });

  it("the server query drops the machine half — the request already goes to that machine", () => {
    expect(workspaceGroupQuery(workspaceGroupKey("/srv/repo", MACHINE))).toBe("/srv/repo");
    expect(workspaceGroupQuery(workspaceGroupKey(TEMP_A, MACHINE))).toBe("temp");
    expect(workspaceGroupQuery("/srv/repo")).toBe("/srv/repo");
    expect(workspaceGroupQuery(TEMP_WORKSPACE_GROUP_KEY)).toBe("temp");
  });

  it("labels are the last path segment; the filesystem root yields '/'", () => {
    expect(workspaceLabel("/srv/penguin/repo")).toBe("repo");
    expect(workspaceLabel("/srv/repo/")).toBe("repo");
    expect(workspaceLabel("/")).toBe("/");
    expect(workspaceLabel("C:\\work\\site")).toBe("site");
  });
});

describe("groupSessionsByWorkspace", () => {
  it("empty input yields no groups", () => {
    expect(groupSessionsByWorkspace([])).toEqual([]);
  });

  it("groups by path across Agents, labels by basename, and keeps the full path for tooltips", () => {
    const a1 = session("/srv/alpha", "2026-07-01T10:00:00.000Z", { agentId: "default_agent" });
    const a2 = session("/srv/alpha", "2026-07-03T10:00:00.000Z", { agentId: "agent_helper" });
    const groups = groupSessionsByWorkspace([a1, a2]);
    expect(groups).toHaveLength(1);
    expect(groups[0]).toMatchObject({
      key: "/srv/alpha",
      label: "alpha",
      fullPath: "/srv/alpha",
      temp: false,
    });
    // Newest first even though the two sessions came from different Agents' lists.
    expect(groups[0]!.sessions.map((s) => s.sessionId)).toEqual([a2.sessionId, a1.sessionId]);
  });

  it("merges every temporary Workspace into one trailing group, after named groups sorted by newest session", () => {
    const oldAlpha = session("/srv/alpha", "2026-07-01T10:00:00.000Z");
    const newAlpha = session("/srv/alpha", "2026-07-06T10:00:00.000Z");
    const beta = session("/srv/beta", "2026-07-05T10:00:00.000Z");
    const temp1 = session(TEMP_A, "2026-07-02T10:00:00.000Z");
    // The newest session overall is a temp one: the temp group still stays last.
    const temp2 = session(TEMP_B, "2026-07-07T10:00:00.000Z");
    const groups = groupSessionsByWorkspace([oldAlpha, beta, temp1, newAlpha, temp2]);
    expect(groups.map((g) => g.key)).toEqual(["/srv/alpha", "/srv/beta", TEMP_WORKSPACE_GROUP_KEY]);
    const temp = groups[2]!;
    expect(temp).toMatchObject({ temp: true, label: "", fullPath: null });
    expect(temp.sessions.map((s) => s.sessionId)).toEqual([temp2.sessionId, temp1.sessionId]);
    expect(groups[0]!.sessions.map((s) => s.sessionId)).toEqual([
      newAlpha.sessionId,
      oldAlpha.sessionId,
    ]);
  });

  it("named-only input has no temp group; temp-only input yields just the temp group", () => {
    expect(
      groupSessionsByWorkspace([session("/srv/alpha", "2026-07-01T10:00:00.000Z")]),
    ).toHaveLength(1);
    const tempOnly = groupSessionsByWorkspace([session(TEMP_A, "2026-07-01T10:00:00.000Z")]);
    expect(tempOnly).toHaveLength(1);
    expect(tempOnly[0]!.key).toBe(TEMP_WORKSPACE_GROUP_KEY);
  });

  it("splits one path across machines into one group each, and names the machine on the group", () => {
    // The sidebar's "+" opens a chat in the group's directory: one merged group would open
    // it here, in whatever this machine happens to have at that path.
    const here = session("/srv/app", "2026-07-01T10:00:00.000Z");
    const there = session("/srv/app", "2026-07-02T10:00:00.000Z");
    const groups = groupSessionsByWorkspace([here, there], (s) =>
      s.sessionId === there.sessionId ? MACHINE : null,
    );
    expect(groups.map((g) => g.key)).toEqual([`${MACHINE}\u0000/srv/app`, "/srv/app"]);
    expect(groups[0]).toMatchObject({ machineId: MACHINE, label: "app", fullPath: "/srv/app" });
    expect(groups[1]).toMatchObject({ machineId: null, label: "app", fullPath: "/srv/app" });
  });

  it("keeps each machine's temporary workspaces in its own temp group", () => {
    const here = session(TEMP_A, "2026-07-01T10:00:00.000Z");
    const there = session(TEMP_B, "2026-07-02T10:00:00.000Z");
    const groups = groupSessionsByWorkspace([here, there], (s) =>
      s.sessionId === there.sessionId ? MACHINE : null,
    );
    expect(groups.map((g) => g.key)).toEqual([
      `${MACHINE}\u0000${TEMP_WORKSPACE_GROUP_KEY}`,
      TEMP_WORKSPACE_GROUP_KEY,
    ]);
    expect(groups.every((g) => g.temp)).toBe(true);
  });

  it("keeps archived sessions in their group (the sidebar splits active/archived per group)", () => {
    const active = session("/srv/alpha", "2026-07-02T10:00:00.000Z");
    const archived = session("/srv/alpha", "2026-07-01T10:00:00.000Z", { archived: true });
    const groups = groupSessionsByWorkspace([archived, active]);
    expect(groups).toHaveLength(1);
    expect(groups[0]!.sessions).toHaveLength(2);
  });
});

describe("sessionCategory (the bucket a Session renders under = the server's list filter)", () => {
  const at = "2026-07-01T10:00:00.000Z";

  it.each(["api", "schedule", "subagent", "cli"] as const)(
    "files a %s Session under Background",
    (source) => {
      expect(sessionCategory(session("/srv/a", at, { source }))).toBe("background");
    },
  );

  it("files a person's conversation, and a row not yet classified, as active", () => {
    expect(sessionCategory(session("/srv/a", at, { source: "user" }))).toBe("active");
    expect(sessionCategory(session("/srv/a", at))).toBe("active");
  });

  it("files an archived Session as archived, whatever its source", () => {
    expect(sessionCategory(session("/srv/a", at, { archived: true }))).toBe("archived");
    expect(sessionCategory(session("/srv/a", at, { source: "cli", archived: true }))).toBe(
      "archived",
    );
  });

  it("files a company Session under no category, archived or not", () => {
    expect(sessionCategory(session("/srv/a", at, { source: "company" }))).toBeNull();
    expect(
      sessionCategory(session("/srv/a", at, { source: "company", archived: true })),
    ).toBeNull();
  });
});

describe("partitionSessions (per-group active / Background / Archived split)", () => {
  it("splits active rows from the Background and Archived folders, preserving order within each part, and puts company rows in none", () => {
    const user1 = session("/srv/alpha", "2026-07-06T10:00:00.000Z", { source: "user" });
    const sched = session("/srv/alpha", "2026-07-05T10:00:00.000Z", { source: "schedule" });
    const sub = session("/srv/alpha", "2026-07-04T10:00:00.000Z", { source: "subagent" });
    const user2 = session("/srv/alpha", "2026-07-03T10:00:00.000Z");
    const cli = session("/srv/alpha", "2026-07-02T10:00:00.000Z", { source: "cli" });
    const gone = session("/srv/alpha", "2026-07-01T10:00:00.000Z", {
      source: "api",
      archived: true,
    });
    // Company mode's desk, live and archived: in no part at all.
    const desk = session("/srv/alpha", "2026-07-05T12:00:00.000Z", { source: "company" });
    const oldDesk = session("/srv/alpha", "2026-06-30T10:00:00.000Z", {
      source: "company",
      archived: true,
    });
    const parts = partitionSessions([user1, desk, sched, sub, user2, cli, gone, oldDesk]);
    expect(parts.active.map((s) => s.sessionId)).toEqual([user1.sessionId, user2.sessionId]);
    expect(parts.background.map((s) => s.sessionId)).toEqual([
      sched.sessionId,
      sub.sessionId,
      cli.sessionId,
    ]);
    expect(parts.archived.map((s) => s.sessionId)).toEqual([gone.sessionId]);
    expect(Object.values(parts).flat()).toHaveLength(6);
  });
});

describe("latestConversation (the auto-opened 'last conversation')", () => {
  it("picks the most recently active person's conversation regardless of input order; archived and background rows never win", () => {
    // Created first but returned to since: this is the conversation the user was last in,
    // and the one created last is not.
    const revisited = session("/srv/a", "2026-07-01T10:00:00.000Z", {
      lastActiveAt: "2026-07-06T10:00:00.000Z",
    });
    const newerUntouched = session("/srv/a", "2026-07-03T10:00:00.000Z", { source: "user" });
    // Active more recently than every conversation, but never auto-opened — a scheduled run
    // included: a program opened it, and the user was not in it.
    const subAfter = session("/srv/a", "2026-07-08T10:00:00.000Z", { source: "subagent" });
    const schedAfter = session("/srv/a", "2026-07-07T10:00:00.000Z", { source: "schedule" });
    const goneAfter = session("/srv/a", "2026-07-09T10:00:00.000Z", { archived: true });
    expect(latestConversation([subAfter, schedAfter, newerUntouched, goneAfter, revisited])).toBe(
      revisited,
    );
  });

  it("never picks a company Session, however recently its desk ran", () => {
    const mine = session("/srv/a", "2026-07-01T10:00:00.000Z");
    const desk = session("/srv/a", "2026-07-02T10:00:00.000Z", {
      source: "company",
      lastActiveAt: "2026-07-10T10:00:00.000Z",
    });
    expect(latestConversation([desk, mine])).toBe(mine);
    expect(latestConversation([desk])).toBeNull();
  });

  it("ties on lastActiveAt break by sessionId, and no qualifying row yields null", () => {
    const at = "2026-07-02T10:00:00.000Z";
    const a = session("/srv/a", at, { sessionId: "session-a" });
    const b = session("/srv/a", at, { sessionId: "session-b" });
    expect(latestConversation([a, b])).toBe(b);
    expect(latestConversation([b, a])).toBe(b);
    expect(latestConversation([])).toBeNull();
    expect(latestConversation([session("/srv/a", at, { source: "cli" })])).toBeNull();
  });
});

describe("splitPage (limit+1 fetch trick)", () => {
  it("an overflow row proves the server has more and is never shown", () => {
    const fetched = [1, 2, 3, 4];
    expect(splitPage(fetched, 3)).toEqual({ items: [1, 2, 3], hasMore: true });
  });

  it("a short or exactly-full page means the server is exhausted", () => {
    expect(splitPage([1, 2], 3)).toEqual({ items: [1, 2], hasMore: false });
    expect(splitPage([1, 2, 3], 3)).toEqual({ items: [1, 2, 3], hasMore: false });
    expect(splitPage([], SIDEBAR_PAGE_SIZE)).toEqual({ items: [], hasMore: false });
  });
});

describe("aggregateWorkspaceCounts (per-group exact server share)", () => {
  const zero = { active: 0, background: 0, archived: 0 };

  it("sums each Workspace path across Agents and records which Agents hold each category", () => {
    const byAgent = new Map<string, Record<string, SessionCategoryCounts>>([
      [
        "agent_a",
        {
          "/srv/alpha": { ...zero, active: 2 },
          "/srv/beta": { ...zero, archived: 3 },
        },
      ],
      ["agent_b", { "/srv/alpha": { ...zero, active: 1, background: 2 } }],
    ]);
    const groups = aggregateWorkspaceCounts(byAgent);
    expect(groups.get("/srv/alpha")).toEqual({
      totals: { active: 3, background: 2, archived: 0 },
      agents: { active: ["agent_a", "agent_b"], background: ["agent_b"], archived: [] },
    });
    expect(groups.get("/srv/beta")).toEqual({
      totals: { ...zero, archived: 3 },
      agents: { active: [], background: [], archived: ["agent_a"] },
    });
    // A group only in another Workspace never appears — its content can't surface elsewhere.
    expect(groups.has("/srv/gamma")).toBe(false);
    expect(aggregateWorkspaceCounts(new Map()).size).toBe(0);
  });

  it("sums the temp group's paths, which the store has already folded onto its key", () => {
    const byAgent = new Map([
      [
        "agent_a",
        {
          [TEMP_WORKSPACE_GROUP_KEY]: { ...zero, active: 3, archived: 1 },
        },
      ],
    ]);
    const groups = aggregateWorkspaceCounts(byAgent);
    expect(groups.size).toBe(1);
    expect(groups.get(TEMP_WORKSPACE_GROUP_KEY)).toEqual({
      totals: { ...zero, active: 3, archived: 1 },
      agents: { active: ["agent_a"], background: [], archived: ["agent_a"] },
    });
  });

  it("counts one path on two machines as two groups (one badge each, matching its own rows)", () => {
    const byAgent = new Map<string, Record<string, SessionCategoryCounts>>([
      [
        "agent_a",
        {
          "/srv/app": { ...zero, active: 2 },
          [`${MACHINE}\u0000/srv/app`]: { ...zero, active: 5 },
        },
      ],
    ]);
    const groups = aggregateWorkspaceCounts(byAgent);
    expect(groups.get("/srv/app")?.totals.active).toBe(2);
    expect(groups.get(`${MACHINE}\u0000/srv/app`)?.totals.active).toBe(5);
  });
});

describe("pinnedFirst (stable pinned-before-unpinned partition)", () => {
  const items = [{ k: "a" }, { k: "b" }, { k: "c" }, { k: "d" }];
  const keyOf = (i: { k: string }) => i.k;
  const keys = (out: { k: string }[]) => out.map((i) => i.k);

  it("empty pinned set keeps the order (and returns a copy, never the input array)", () => {
    const out = pinnedFirst(items, keyOf, new Set());
    expect(keys(out)).toEqual(["a", "b", "c", "d"]);
    expect(out).not.toBe(items);
  });

  it("pinned items move to the front, each partition preserving the input order", () => {
    expect(keys(pinnedFirst(items, keyOf, new Set(["c", "a"])))).toEqual(["a", "c", "b", "d"]);
    expect(keys(pinnedFirst(items, keyOf, new Set(["d"])))).toEqual(["d", "a", "b", "c"]);
  });

  it("pinned keys with no matching item are ignored; all-pinned keeps the order", () => {
    expect(keys(pinnedFirst(items, keyOf, new Set(["nope"])))).toEqual(["a", "b", "c", "d"]);
    expect(keys(pinnedFirst(items, keyOf, new Set(["a", "b", "c", "d"])))).toEqual([
      "a",
      "b",
      "c",
      "d",
    ]);
  });

  it("pinning the merged temp group lifts it above named workspace groups", () => {
    const groups = groupSessionsByWorkspace([
      session("/srv/alpha", "2026-07-02T10:00:00.000Z"),
      session(TEMP_A, "2026-07-01T10:00:00.000Z"),
    ]);
    expect(groups.map((g) => g.key)).toEqual(["/srv/alpha", TEMP_WORKSPACE_GROUP_KEY]);
    const pinned = pinnedFirst(groups, (g) => g.key, new Set([TEMP_WORKSPACE_GROUP_KEY]));
    expect(pinned.map((g) => g.key)).toEqual([TEMP_WORKSPACE_GROUP_KEY, "/srv/alpha"]);
  });

  it("agent-mode ordering: pinned agentIds lift agents, the unpinned keep the configured order", () => {
    // The sidebar's agent mode partitions the Project's Agent list (agentId is the group key).
    const agents = [{ agentId: "default_agent" }, { agentId: "agent_a" }, { agentId: "agent_b" }];
    const byId = (a: { agentId: string }) => a.agentId;
    expect(pinnedFirst(agents, byId, new Set(["agent_b"])).map(byId)).toEqual([
      "agent_b",
      "default_agent",
      "agent_a",
    ]);
    // Multiple pinned Agents keep their relative configured order inside the pinned partition.
    expect(pinnedFirst(agents, byId, new Set(["agent_b", "default_agent"])).map(byId)).toEqual([
      "default_agent",
      "agent_b",
      "agent_a",
    ]);
  });
});

describe("matchesSessionQuery (sidebar live title search)", () => {
  const titled = (title: string): SessionInfo => ({
    ...session("/w", "2026-08-13T00:00:00Z"),
    title,
  });

  it("matches case-insensitive substrings of the title, ignoring surrounding whitespace in the query", () => {
    const s = titled("Fix login bug");
    expect(matchesSessionQuery(s, "login")).toBe(true);
    expect(matchesSessionQuery(s, "FIX")).toBe(true);
    expect(matchesSessionQuery(s, "  bug  ")).toBe(true);
    expect(matchesSessionQuery(s, "logout")).toBe(false);
  });

  it("a blank or whitespace-only query matches everything (search inactive)", () => {
    expect(matchesSessionQuery(titled("anything"), "")).toBe(true);
    expect(matchesSessionQuery(titled("anything"), "   ")).toBe(true);
    expect(matchesSessionQuery(session("/w", "2026-08-13T00:00:00Z"), "")).toBe(true);
  });

  it("untitled Sessions never match a non-empty query (no stored title to search)", () => {
    expect(matchesSessionQuery(session("/w", "2026-08-13T00:00:00Z"), "new")).toBe(false);
  });
});

/**
 * Time buckets (the sidebar's "by time" grouping): last day / last month / earlier, cut on
 * `lastActiveAt` against a caller-supplied "now" so the boundaries are testable without a
 * clock. The bucket a row lands in must agree with the compact relative timestamp rendered
 * beside it, which reads the same field.
 */
const NOW = Date.parse("2026-08-21T12:00:00.000Z");
const ago = (ms: number) => new Date(NOW - ms).toISOString();
const HOUR = 60 * 60 * 1000;
const DAY = 24 * HOUR;

describe("timeBucketOf", () => {
  it("cuts at 24 hours and at 30 days, the older side of each boundary losing", () => {
    expect(timeBucketOf(ago(0), NOW)).toBe("day");
    expect(timeBucketOf(ago(DAY - 1), NOW)).toBe("day");
    expect(timeBucketOf(ago(DAY), NOW)).toBe("month");
    expect(timeBucketOf(ago(30 * DAY - 1), NOW)).toBe("month");
    expect(timeBucketOf(ago(30 * DAY), NOW)).toBe("earlier");
  });

  it("puts a clock-skewed future stamp in the newest bucket, and an unreadable one in the oldest", () => {
    expect(timeBucketOf(new Date(NOW + HOUR).toISOString(), NOW)).toBe("day");
    // Never the top of the list on a value nothing can be concluded from.
    expect(timeBucketOf("", NOW)).toBe("earlier");
    expect(timeBucketOf("not-a-date", NOW)).toBe("earlier");
  });
});

describe("groupSessionsByTime", () => {
  it("renders newest bucket first and drops the empty ones", () => {
    const groups = groupSessionsByTime(
      [session("/w", ago(40 * DAY)), session("/w", ago(2 * HOUR))],
      NOW,
    );
    expect(groups.map((g) => g.bucket)).toEqual(["day", "earlier"]);
    expect(groups.map((g) => g.key)).toEqual([timeGroupKey("day"), timeGroupKey("earlier")]);
    expect(groupSessionsByTime([], NOW)).toEqual([]);
  });

  it("buckets and sorts on last activity, not on creation", () => {
    // An old conversation used today belongs where its own timestamp says it does: the row
    // reads "2h ago", so a bucket claiming it is older would contradict the row beside it.
    const revived = session("/w", ago(90 * DAY), {
      sessionId: "session-revived",
      lastActiveAt: ago(2 * HOUR),
    });
    const fresh = session("/w", ago(3 * DAY), {
      sessionId: "session-fresh",
      lastActiveAt: ago(3 * HOUR),
    });
    const groups = groupSessionsByTime([fresh, revived], NOW);
    expect(groups).toHaveLength(1);
    expect(groups[0]?.bucket).toBe("day");
    expect(groups[0]?.sessions.map((s) => s.sessionId)).toEqual([
      "session-revived",
      "session-fresh",
    ]);
  });

  it("keys buckets so they can never collide with a Workspace path or an Agent id", () => {
    const keys = TIME_BUCKETS.map(timeGroupKey);
    expect(new Set([...keys, TIME_FOLDERS_GROUP_KEY, TEMP_WORKSPACE_GROUP_KEY]).size).toBe(
      keys.length + 2,
    );
    // "\0" is the one byte a filesystem path and an Agent id cannot contain.
    for (const key of [...keys, TIME_FOLDERS_GROUP_KEY]) expect(key.startsWith("\0")).toBe(true);
  });
});

describe("totalCategoryCounts", () => {
  const counts = (over: Partial<SessionCategoryCounts>): SessionCategoryCounts => ({
    active: 0,
    background: 0,
    archived: 0,
    ...over,
  });

  it("sums every Agent's share, since a time bucket spans all of them", () => {
    expect(
      totalCategoryCounts(
        new Map([
          ["a", counts({ active: 3, archived: 2 })],
          ["b", counts({ active: 4, background: 1 })],
        ]),
      ),
    ).toEqual({ active: 7, background: 1, archived: 2 });
  });

  it("reports zeros for an empty map rather than leaving fields undefined", () => {
    expect(totalCategoryCounts(new Map())).toEqual({ active: 0, background: 0, archived: 0 });
  });
});

describe("aggregateWorkspaceLatest (per-group newest-Session stamp)", () => {
  it("keeps the newest stamp per path across Agents, and the newest temporary path for the temp group", () => {
    const byAgent = new Map<string, Record<string, string>>([
      [
        "agent_a",
        {
          "/srv/alpha": "2026-07-03T09:00:00.000Z",
          [TEMP_A]: "2026-07-03T08:00:00.000Z",
        },
      ],
      [
        "agent_b",
        {
          "/srv/alpha": "2026-07-03T09:30:00.000Z",
          "/srv/beta": "2026-07-01T00:00:00.000Z",
          [TEMP_B]: "2026-07-03T08:30:00.000Z",
        },
      ],
    ]);
    const latest = aggregateWorkspaceLatest(byAgent);
    expect(latest.get("/srv/alpha")).toBe("2026-07-03T09:30:00.000Z");
    expect(latest.get("/srv/beta")).toBe("2026-07-01T00:00:00.000Z");
    expect(latest.get(TEMP_WORKSPACE_GROUP_KEY)).toBe("2026-07-03T08:30:00.000Z");
    expect(latest.size).toBe(3);
    expect(aggregateWorkspaceLatest(new Map()).size).toBe(0);
  });
});

describe("completeWorkspaceGroups (every counted Workspace is a group, placed by recency)", () => {
  const zero = { active: 0, background: 0, archived: 0 };
  const counted = (totals: Partial<SessionCategoryCounts>) => ({
    totals: { ...zero, ...totals },
    agents: { active: [], background: [], archived: [] },
  });

  it("reads a machine-qualified count key as that machine's directory, not as a path", () => {
    const key = workspaceGroupKey("/srv/alpha", "gpu-box");
    const groups = completeWorkspaceGroups([], new Map([[key, counted({ active: 1 })]]), new Map());
    expect(groups).toEqual([
      {
        key,
        label: workspaceLabel("/srv/alpha"),
        fullPath: "/srv/alpha",
        machineId: "gpu-box",
        temp: false,
        sessions: [],
      },
    ]);
  });

  it("adds an empty group for a counted Workspace the loaded rows never touched, and orders every group by its newest stamp", () => {
    // Loaded: one Agent's first page reached only alpha (newest) and a temp workspace.
    const loaded = groupSessionsByWorkspace([
      session("/srv/alpha", "2026-07-03T09:00:00.000Z"),
      session(TEMP_A, "2026-07-02T12:00:00.000Z"),
    ]);
    const counts = new Map([
      ["/srv/alpha", counted({ active: 40 })],
      // Unloaded, newer than alpha's loaded row: the stamp places it first.
      ["/srv/beta", counted({ active: 300 })],
      // Unloaded, older: last among the named groups.
      ["/srv/gamma", counted({ active: 2, archived: 5 })],
      [TEMP_WORKSPACE_GROUP_KEY, counted({ active: 7 })],
    ]);
    const latest = new Map([
      ["/srv/alpha", "2026-07-03T09:00:00.000Z"],
      ["/srv/beta", "2026-07-03T10:00:00.000Z"],
      ["/srv/gamma", "2026-06-01T00:00:00.000Z"],
      [TEMP_WORKSPACE_GROUP_KEY, "2026-07-03T11:00:00.000Z"],
    ]);
    const groups = completeWorkspaceGroups(loaded, counts, latest);
    expect(groups.map((g) => g.key)).toEqual([
      "/srv/beta",
      "/srv/alpha",
      "/srv/gamma",
      TEMP_WORKSPACE_GROUP_KEY,
    ]);
    const beta = groups[0]!;
    expect(beta).toMatchObject({ label: "beta", fullPath: "/srv/beta", temp: false });
    expect(beta.sessions).toEqual([]);
    // Groups already formed keep their loaded rows.
    expect(groups[1]!.sessions).toHaveLength(1);
    // The temp group stays last however new its stamp is, and keeps its loaded row.
    expect(groups[3]!.sessions).toHaveLength(1);
  });

  it("places a group by its newest loaded row when that is newer than the stamp (a conversation added since the counts)", () => {
    const loaded = groupSessionsByWorkspace([
      session("/srv/alpha", "2026-07-03T12:00:00.000Z"),
      session("/srv/beta", "2026-07-03T09:00:00.000Z"),
    ]);
    const counts = new Map([
      ["/srv/alpha", counted({ active: 1 })],
      ["/srv/beta", counted({ active: 1 })],
    ]);
    // Stale stamps say beta is newer; alpha's loaded row is newer than both.
    const latest = new Map([
      ["/srv/alpha", "2026-07-01T00:00:00.000Z"],
      ["/srv/beta", "2026-07-02T00:00:00.000Z"],
    ]);
    expect(completeWorkspaceGroups(loaded, counts, latest).map((g) => g.key)).toEqual([
      "/srv/alpha",
      "/srv/beta",
    ]);
  });

  it("forms no group for a counted key with nothing left in any category, and none without counts", () => {
    const loaded = groupSessionsByWorkspace([session("/srv/alpha", "2026-07-03T09:00:00.000Z")]);
    const counts = new Map([
      ["/srv/alpha", counted({ active: 1 })],
      ["/srv/gone", counted({})],
    ]);
    expect(completeWorkspaceGroups(loaded, counts, new Map()).map((g) => g.key)).toEqual([
      "/srv/alpha",
    ]);
    expect(completeWorkspaceGroups(loaded, new Map(), new Map()).map((g) => g.key)).toEqual([
      "/srv/alpha",
    ]);
    expect(completeWorkspaceGroups([], new Map(), new Map())).toEqual([]);
  });

  it("forms the temp group from its counts alone, empty and last, when no temporary row is loaded", () => {
    const loaded = groupSessionsByWorkspace([session("/srv/alpha", "2026-07-03T09:00:00.000Z")]);
    const counts = new Map([[TEMP_WORKSPACE_GROUP_KEY, counted({ archived: 3 })]]);
    const groups = completeWorkspaceGroups(loaded, counts, new Map());
    expect(groups.map((g) => g.key)).toEqual(["/srv/alpha", TEMP_WORKSPACE_GROUP_KEY]);
    expect(groups[1]).toMatchObject({ label: "", fullPath: null, temp: true, sessions: [] });
  });
});

describe("the activity order", () => {
  const key = (lastActiveAt: string, sessionId: string): ActivityKey => ({
    lastActiveAt,
    sessionId,
  });
  const ids = (keys: ActivityKey[]) => keys.map((k) => k.sessionId);

  it("puts the most recent activity first, then the higher id", () => {
    const rows = [
      key("2026-09-01T00:00:00.000Z", "s-b"),
      key("2026-09-02T00:00:00.000Z", "s-a"),
      key("2026-09-01T00:00:00.000Z", "s-c"),
    ];
    expect(ids([...rows].sort(compareActivityDesc))).toEqual(["s-a", "s-c", "s-b"]);
  });

  it("compares by code point where a locale's collation would order the pair the other way", () => {
    // The browser names the cursor and the server slices on it: both must agree on one order.
    const stamp = "2026-09-01T00:00:00.000Z";
    for (const [higher, lower] of [
      ["session-abcd", "session-ABCD"],
      ["session-a_b", "session-a-b"],
    ] as const) {
      expect(higher.localeCompare(lower, "en")).toBeLessThan(0);
      expect(compareActivityDesc(key(stamp, higher), key(stamp, lower))).toBeLessThan(0);
    }
  });

  it("names a cursor as <lastActiveAt>,<sessionId>", () => {
    expect(activityCursorParam(key("2026-09-01T00:00:00.000Z", "session-x"))).toBe(
      "2026-09-01T00:00:00.000Z,session-x",
    );
  });
});

describe("the watermark of a merged list", () => {
  const at = (day: number, sessionId = `s-${day}`): ActivityKey => ({
    lastActiveAt: `2026-09-${String(day).padStart(2, "0")}T00:00:00.000Z`,
    sessionId,
  });

  it("is the most recent cursor among the streams that still have more", () => {
    expect(
      activityWatermark([
        { hasMore: true, cursor: at(3) },
        { hasMore: true, cursor: at(7) },
        // Exhausted: everything it holds is already in hand, however recent its last row.
        { hasMore: false, cursor: at(9) },
      ]),
    ).toEqual(at(7));
  });

  it("is absent when no stream has more, and a stream with nothing read bounds nothing", () => {
    expect(activityWatermark([])).toBeNull();
    expect(activityWatermark([{ hasMore: false, cursor: at(3) }])).toBeNull();
    expect(
      activityWatermark([
        { hasMore: true, cursor: null },
        { hasMore: true, cursor: at(2) },
      ]),
    ).toEqual(at(2));
  });

  it("the cut keeps the rows at or above it, in order, and the open conversation wherever it falls", () => {
    const rows = [at(1), at(5), at(3), at(4), at(2)];
    expect(cutAtWatermark(rows, at(3)).map((r) => r.sessionId)).toEqual(["s-5", "s-4", "s-3"]);
    expect(cutAtWatermark(rows, at(3), "s-1").map((r) => r.sessionId)).toEqual([
      "s-5",
      "s-4",
      "s-3",
      "s-1",
    ]);
    expect(cutAtWatermark(rows, null).map((r) => r.sessionId)).toEqual([
      "s-5",
      "s-4",
      "s-3",
      "s-2",
      "s-1",
    ]);
  });
});

/** A seeded linear congruential generator: deterministic runs whose failures name their seed. */
function lcg(seed: number): () => number {
  let state = seed >>> 0;
  return () => {
    state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
    return state / 2 ** 32;
  };
}

describe("property: a list merged from cursor-paged streams", () => {
  /** One server stream and the client's position in it. */
  interface Stream extends StreamPosition {
    rows: ActivityKey[];
  }

  it("is a prefix of the true order after any loads and flips, and loads only append", () => {
    const STAMPS = [1, 2, 3, 5, 8].map((d) => `2026-09-0${d}T00:00:00.000Z`);
    for (let seed = 1; seed <= 200; seed += 1) {
      const rand = lcg(seed);
      const int = (n: number) => Math.floor(rand() * n);
      let n = 0;
      const streams: Stream[] = Array.from({ length: 1 + int(4) }, () => ({
        hasMore: false,
        cursor: null,
        rows: Array.from({ length: int(26) }, () => ({
          lastActiveAt: STAMPS[int(STAMPS.length)]!,
          sessionId: `s${String(n++).padStart(3, "0")}`,
        })),
      }));
      /** What the client holds: its own copy of each row it was served or fetched. */
      const pool = new Map<string, ActivityKey>();
      let clock = Date.parse("2026-09-20T00:00:00.000Z");

      /** The server answering a page: the rows strictly below the cursor, one extra for "more". */
      const load = (stream: Stream) => {
        const below = [...stream.rows]
          .sort(compareActivityDesc)
          .filter((r) => stream.cursor === null || compareActivityDesc(r, stream.cursor) > 0);
        const { items, hasMore } = splitPage(
          below.slice(0, SIDEBAR_PAGE_SIZE + 1),
          SIDEBAR_PAGE_SIZE,
        );
        for (const r of items) pool.set(r.sessionId, { ...r });
        const last = items.at(-1);
        stream.hasMore = hasMore;
        if (last !== undefined) stream.cursor = { ...last };
      };
      const view = () => cutAtWatermark([...pool.values()], activityWatermark(streams));
      const truth = () =>
        streams
          .flatMap((s) => s.rows)
          .sort(compareActivityDesc)
          .map((r) => r.sessionId);
      const expectPrefix = (what: string) => {
        const shown = view().map((r) => r.sessionId);
        expect(shown, `seed ${seed}, ${what}`).toEqual(truth().slice(0, shown.length));
      };

      for (const stream of streams) load(stream);
      expectPrefix("first pages");
      for (let step = 1; step <= 30; step += 1) {
        const roll = rand();
        const withMore = streams.filter((s) => s.hasMore);
        if (roll < 0.65 && withMore.length > 0) {
          const every = roll < 0.25;
          const chosen = every ? withMore : withMore.filter(() => rand() < 0.5);
          if (chosen.length === 0) chosen.push(withMore[int(withMore.length)]!);
          const before = view();
          for (const stream of chosen) load(stream);
          const what = `step ${step}: load ${every ? "every stream" : "some streams"}`;
          expectPrefix(what);
          const after = view();
          expect(after.slice(0, before.length), `seed ${seed}, ${what}`).toEqual(before);
          const floor = before.at(-1);
          if (floor !== undefined) {
            for (const r of after.slice(before.length)) {
              expect(compareActivityDesc(r, floor), `seed ${seed}, ${what}`).toBeGreaterThan(0);
            }
          }
          if (every) {
            const remaining = truth().length - before.length;
            expect(after.length - before.length, `seed ${seed}, ${what}`).toBeGreaterThanOrEqual(
              Math.min(SIDEBAR_PAGE_SIZE, remaining),
            );
          }
        } else {
          const all = streams.flatMap((s) => s.rows);
          if (all.length === 0) continue;
          const row = all[int(all.length)]!;
          clock += 60_000;
          row.lastActiveAt = new Date(clock).toISOString();
          // Loaded: its own key rises in place. Not loaded: the event fetches it (it has moved
          // above every cursor, so no page will serve it again).
          pool.set(row.sessionId, { ...row });
          expectPrefix(`step ${step}: flip ${row.sessionId}`);
        }
      }
    }
  });
});