@omercnet/paseo-beads 1.1.0 → 1.2.0

package/README.md

@@ -4,7 +4,8 @@ A dependency-aware Beads work queue for every Paseo workspace. Paseo Beads turns
 a read-only delivery view that makes the ready frontier, work in progress, and blockers immediately
 visible.
 
-It adds a workspace-scoped **Beads** Explorer panel and an **Open Beads** Command Center item.
+It adds a workspace-scoped **Beads** Explorer panel and an **Open Beads** Command Center item. On
+Paseo 0.11 and newer it also adds a **Ready beads** sidebar row and a linkable bead screen.
 
 ## Demo
 
@@ -36,6 +37,10 @@ verified the rendered page contained no private organization names.
   layouts.
 - A virtualized issue list, descriptive accessibility labels, and focus restoration when navigating
   between the compact list and detail view.
+- On Paseo 0.11 and newer, a **Ready beads** sidebar row with the number of ready beads across the
+  host's workspaces. Pressing it opens a popover (a bottom sheet in compact layouts) with the top 10
+  ready beads grouped by workspace. Pressing a bead opens its detail view as a screen whose URL
+  carries the workspace and bead IDs, so it can be linked and survives a reload.
 
 Within each lane, issues are ordered by priority, most recent update, then ID. In-progress and hooked
 issues enter **In progress** first; remaining blocked issues enter **Blocked**; ready issues enter
@@ -47,7 +52,10 @@ The panel calls workspace-scoped Paseo plugin RPC handlers. On the daemon host,
 the workspace directory through Paseo and executes the `bd` CLI with `--readonly` and `-C`:
 
 - The list handler runs `bd list --json --sort priority`, then runs one authoritative
-  `bd list --ready --json --limit 0` query and intersects its IDs with the displayed issues.
+  `bd list --ready --json --limit 0` query and intersects its IDs with the displayed issues. It also
+  runs `bd where --json` and returns a digest of the database location as an opaque `databaseId`,
+  so workspaces that share one database, such as git worktrees, can be recognized. This is best
+  effort: when `bd` cannot say, the snapshot is the same without it.
 - Selecting an issue runs `bd show <issue-id> --json --include-dependents` plus the same authoritative
   readiness query.
 
@@ -58,9 +66,23 @@ The list and selected detail poll every 10 seconds. **Refresh** requests the lis
 failed background refresh keeps the previous data visible with an inline error; initial and detail
 failures provide a retry action.
 
+The **Ready beads** row lists the host's workspaces through the Paseo SDK and calls the same list
+handler for them, one workspace at a time, every 2 minutes while the app is in the foreground and
+whenever its popover opens. A snapshot an open panel read in the last 10 seconds is reused instead
+of rerunning `bd`. Workspaces that share a database, such as git worktrees, report the same
+`databaseId`, so an issue counts once however many workspaces read it and is listed under the first
+workspace that reported it. The first scan reads every workspace to learn which ones share a
+database. Later scans read each database once and skip its other workspaces. A workspace is skipped
+only while a successful read in the last 10 minutes vouches that it reads a database the scan has
+already read, so a failed or older read puts it back in the scan. Workspaces without Beads count as
+zero and are rechecked every 5 minutes. When `bd` is unavailable, or a workspace cannot be read,
+the popover says so instead of reporting an empty host, and a failed refresh is shown next to the
+last result. Once nothing shows the count, for example when the host disconnects, a scan that is
+still running starts no further workspace reads.
+
 ## Limits
 
-- Paseo `^0.9.0 || ^0.10.0` with plugins enabled is required.
+- Paseo `^0.9.0 || ^0.10.0 || ^0.11.0` with plugins enabled is required.
 - Beads `bd` 1.0 or newer must be available on the Paseo daemon's `PATH`.
 - A Beads project must be initialized in the workspace for issue data to appear.
 - CLI calls time out after 10 seconds and accept at most 8 MiB of output. Unexpected CLI details stay
@@ -74,6 +96,15 @@ failures provide a retry action.
   project, request failures, and missing issue details.
 - This plugin is read-only and workspace-scoped. It uses the `bd` CLI exclusively and does not
   create, edit, close, or assign issues.
+- The **Ready beads** row and the bead screen need Paseo 0.11. On 0.9 and 0.10 they do not register,
+  and the panel and Command Center items work as before.
+- The **Ready beads** count covers the first 200 workspaces the host lists and, like the panel, the
+  first 500 issues of each workspace. It refreshes about every two minutes while the app is in the
+  foreground, plus the time a scan takes, and when the popover opens, so it can be older after the
+  app was in the background. A workspace that moves to another database is noticed within 10
+  minutes.
+- A `bd` that cannot report its database (`bd where --json`) leaves every workspace counted on its
+  own, so git worktrees of one project are counted separately.
 
 ## Install
 
@@ -96,7 +127,8 @@ Paseo shows the installed and proposed revisions and asks for approval before ap
 update. Review the source changes before approving them.
 
 Open a workspace, choose **New tab** in Explorer, then select **Beads**. You can also run **Open
-Beads** from the Command Center while viewing a workspace or one of its agents.
+Beads** from the Command Center while viewing a workspace or one of its agents. On Paseo 0.11 and
+newer, press **Ready beads** in the sidebar for ready work across every workspace on the host.
 
 ## Develop
 

package/client/beads-view.ts

@@ -1,4 +1,4 @@
-import type { BeadSummary } from "../shared/beads";
+import { type BeadSummary, type BeadsSnapshot, getWorkspaceBead } from "../shared/beads";
 
 export const BEAD_LANES = ["ready", "in_progress", "blocked", "other"] as const;
 
@@ -153,3 +153,106 @@ export function buildBeadsView(
 
   return { lanes, counts };
 }
+
+export const BEAD_SCREEN_ID = "bead";
+
+/** Reads bead screen params (`{ workspace, bead }`) with the detail RPC's own input rules. */
+export function parseBeadScreenParams(params: Readonly<Record<string, string>>) {
+  const parsed = getWorkspaceBead.input.safeParse({
+    workspaceId: params.workspace,
+    issueId: params.bead,
+  });
+  return parsed.success ? parsed.data : null;
+}
+
+/** Shared by the panel and the sidebar count, so either one reuses the other's snapshot. */
+export function beadsSnapshotQueryKey(hostId: string, workspaceId: string) {
+  return ["paseo-beads", "snapshot", hostId, workspaceId] as const;
+}
+
+export interface ReadyBeadsWorkspace {
+  id: string;
+  projectDisplayName: string;
+  name: string;
+}
+
+export interface ReadyBeadsSummary {
+  /** Ready beads across every workspace that loaded. */
+  count: number;
+  /** The top ready beads, grouped under the workspace each one is listed for. */
+  groups: { workspace: ReadyBeadsWorkspace; beads: BeadSummary[] }[];
+  /** Workspaces whose snapshot failed to load. */
+  failed: number;
+  /** Workspaces on a host that cannot run `bd`. */
+  unavailable: number;
+}
+
+/**
+ * Workspaces that share a Beads database, such as git worktrees, report the same `databaseId`, so
+ * an issue counts once and is listed under the first workspace that reported it. Titles are
+ * display data, not identity. A snapshot that cannot name its database counts as having its own.
+ */
+export function summarizeReadyBeads(
+  entries: readonly { workspace: ReadyBeadsWorkspace; snapshot: BeadsSnapshot | null }[],
+  limit: number,
+): ReadyBeadsSummary {
+  const seen = new Set<string>();
+  const ready: { workspace: ReadyBeadsWorkspace; bead: BeadSummary }[] = [];
+  let failed = 0;
+  let unavailable = 0;
+
+  for (const { workspace, snapshot } of entries) {
+    if (!snapshot) failed += 1;
+    else if (snapshot.state === "bd_unavailable") unavailable += 1;
+    const database = snapshot?.databaseId ?? workspace.id;
+    for (const bead of snapshot?.issues ?? []) {
+      const key = JSON.stringify([database, bead.id]);
+      if (beadLaneFor(bead) !== "ready" || seen.has(key)) continue;
+      seen.add(key);
+      ready.push({ workspace, bead });
+    }
+  }
+  ready.sort((left, right) => compareBeads(left.bead, right.bead));
+
+  const groups = new Map<string, ReadyBeadsSummary["groups"][number]>();
+  for (const { workspace, bead } of ready.slice(0, limit)) {
+    const group = groups.get(workspace.id) ?? { workspace, beads: [] };
+    group.beads.push(bead);
+    groups.set(workspace.id, group);
+  }
+
+  return { count: ready.length, groups: [...groups.values()], failed, unavailable };
+}
+
+export interface ReadyBeadsNotes {
+  /** Replaces the list when no ready bead was found; qualified when the result is incomplete. */
+  empty: string | null;
+  /** Caveats about the result, shown below it. */
+  notices: string[];
+}
+
+/** `refreshError` is the message of a failed refresh that left the previous result in place. */
+export function describeReadyBeads(
+  { count, failed, unavailable }: ReadyBeadsSummary,
+  refreshError: string | null,
+): ReadyBeadsNotes {
+  const notices: string[] = [];
+  if (refreshError) notices.push(`Refresh failed, showing the last result. ${refreshError}`);
+  if (failed > 0) {
+    notices.push(`${failed === 1 ? "1 workspace" : `${failed} workspaces`} could not be read.`);
+  }
+  if (unavailable > 0 && count > 0) {
+    notices.push(
+      `The bd CLI was unavailable for ${unavailable === 1 ? "1 workspace" : `${unavailable} workspaces`}, so the count may be incomplete.`,
+    );
+  }
+
+  let empty: string | null = null;
+  if (count === 0) {
+    if (unavailable > 0) empty = "The bd CLI is not available on this Paseo host.";
+    else if (failed > 0 || refreshError) {
+      empty = "No ready beads found in the workspaces that could be checked.";
+    } else empty = "No ready beads in any workspace on this host.";
+  }
+  return { empty, notices };
+}

package/client/paseo-beads.tsx

@@ -1,4 +1,9 @@
-import { type PluginWorkspacePanelProps, useRpc, useWorkspace } from "@getpaseo/plugin/client";
+import {
+  type PluginScreenProps,
+  type PluginWorkspacePanelProps,
+  useRpc,
+  useWorkspace,
+} from "@getpaseo/plugin/client";
 import { Icon } from "@getpaseo/plugin/client/react-native";
 import { useQuery } from "@tanstack/react-query";
 import { type ReactNode, type RefObject, useEffect, useMemo, useRef, useState } from "react";
@@ -30,16 +35,18 @@ import {
   type BeadLane,
   type BeadSection,
   type BeadsFilter,
+  beadsSnapshotQueryKey,
   buildBeadSections,
   buildBeadsView,
   issueAccessibilityLabel,
+  parseBeadScreenParams,
 } from "./beads-view";
 import { focusWebElement } from "./web";
 
 const REFRESH_INTERVAL_MS = 10_000;
 const BACK_BUTTON_NATIVE_ID = "paseo-beads-back";
 const ISSUE_ROW_NATIVE_ID_PREFIX = "paseo-beads-issue-";
-const ID_FONT_FAMILY = Platform.select({ ios: "Menlo", default: "monospace" });
+export const ID_FONT_FAMILY = Platform.select({ ios: "Menlo", default: "monospace" });
 
 const FILTERS: readonly { id: BeadsFilter; title: string }[] = [
   { id: "all", title: "All" },
@@ -47,7 +54,7 @@ const FILTERS: readonly { id: BeadsFilter; title: string }[] = [
   { id: "assigned", title: "Assigned" },
 ];
 
-function errorMessage(error: unknown): string {
+export function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : "An unexpected error occurred.";
 }
 
@@ -69,7 +76,7 @@ function laneColor(lane: BeadLane, colors: PluginWorkspacePanelProps["theme"]["c
   return colors.foregroundMuted;
 }
 
-function priorityColor(
+export function priorityColor(
   priority: number,
   colors: PluginWorkspacePanelProps["theme"]["colors"],
 ): string {
@@ -214,13 +221,13 @@ function DetailPane({
   styles,
   theme,
 }: {
-  backButtonRef: RefObject<View | null>;
+  backButtonRef?: RefObject<View | null>;
   detail: BeadDetail | null | undefined;
   detailError: unknown;
   isDetailFetching: boolean;
   isDetailPending: boolean;
   missing: boolean;
-  onBack(): void;
+  onBack?(): void;
   onRetry(): void;
   selectedId: string | null;
   showBack: boolean;
@@ -434,6 +441,45 @@ export function PaseoBeads(props: PluginWorkspacePanelProps) {
   return <WorkspaceBeads key={props.workspaceId} {...props} />;
 }
 
+export function BeadScreen({ theme, layout, host, params }: PluginScreenProps) {
+  const styles = useMemo(() => createStyles(theme, layout.compact), [layout.compact, theme]);
+  const target = parseBeadScreenParams(params);
+  const loadDetail = useRpc(getWorkspaceBead);
+  const { data, error, isFetching, isPending, refetch } = useQuery({
+    queryKey: ["paseo-beads", "detail", host.id, target?.workspaceId, target?.issueId],
+    queryFn: () => loadDetail(target as NonNullable<typeof target>),
+    enabled: target !== null,
+    refetchInterval: REFRESH_INTERVAL_MS,
+  });
+
+  return (
+    <View style={styles.screen}>
+      {target ? (
+        <DetailPane
+          detail={data?.detail}
+          detailError={error}
+          isDetailFetching={isFetching}
+          isDetailPending={isPending}
+          missing={data?.detail === null}
+          onRetry={() => void refetch()}
+          selectedId={target.issueId}
+          showBack={false}
+          styles={styles}
+          theme={theme}
+        />
+      ) : (
+        <StateCard
+          body="This link needs a workspace ID and a bead ID."
+          icon="AlertTriangle"
+          styles={styles}
+          theme={theme}
+          title="Invalid bead link"
+        />
+      )}
+    </View>
+  );
+}
+
 function WorkspaceBeads({ theme, layout, host, workspaceId }: PluginWorkspacePanelProps) {
   const styles = useMemo(() => createStyles(theme, layout.compact), [layout.compact, theme]);
   const workspaceTitle = useWorkspace(workspaceId, ({ name, title }) => title?.trim() || name);
@@ -449,7 +495,7 @@ function WorkspaceBeads({ theme, layout, host, workspaceId }: PluginWorkspacePan
   const listScrollOffsetRef = useRef(0);
 
   const snapshotKey = useMemo(
-    () => ["paseo-beads", "snapshot", host.id, workspaceId] as const,
+    () => beadsSnapshotQueryKey(host.id, workspaceId),
     [host.id, workspaceId],
   );
   const {

package/client/ready-beads.tsx

@@ -0,0 +1,159 @@
+import {
+  type PluginPopoverProps,
+  type PluginSidebarItemProps,
+  usePaseo,
+  useRpc,
+} from "@getpaseo/plugin/client";
+import { SidebarRow } from "@getpaseo/plugin/client/ui";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { ActivityIndicator, Pressable, StyleSheet, Text, View } from "react-native";
+import { getWorkspaceBeads } from "../shared/beads";
+import { BEAD_SCREEN_ID, describeReadyBeads } from "./beads-view";
+import { errorMessage, ID_FONT_FAMILY, priorityColor } from "./paseo-beads";
+import { READY_LIST_LIMIT, scanReadyBeads } from "./ready-scan";
+
+/** The scan reads every project's Beads, so it runs rarely in the background and on popover open. */
+const READY_REFRESH_INTERVAL_MS = 120_000;
+
+function useReadyBeads(hostId: string, refetchOnMount: true | "always") {
+  const paseo = usePaseo();
+  const queryClient = useQueryClient();
+  const loadSnapshot = useRpc(getWorkspaceBeads);
+  return useQuery({
+    queryKey: ["paseo-beads", "ready", hostId],
+    queryFn: ({ signal }) =>
+      scanReadyBeads({
+        hostId,
+        signal,
+        queryClient,
+        loadSnapshot,
+        listWorkspaces: async () => (await paseo.workspaces.list()).entries,
+      }),
+    staleTime: READY_REFRESH_INTERVAL_MS / 2,
+    refetchInterval: READY_REFRESH_INTERVAL_MS,
+    refetchOnMount,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function ReadyBeadsItem({
+  theme,
+  host,
+  currentScreen,
+  openPopover,
+}: PluginSidebarItemProps) {
+  const { data } = useReadyBeads(host.id, true);
+  return (
+    <SidebarRow
+      icon="CircleDot"
+      active={currentScreen?.screenId === BEAD_SCREEN_ID}
+      onPress={() => openPopover(ReadyBeadsPopover)}
+      trailing={
+        data?.count ? (
+          <Text style={{ color: theme.colors.foregroundMuted, fontSize: 12 }}>{data.count}</Text>
+        ) : null
+      }
+    />
+  );
+}
+
+function ReadyBeadsPopover({ theme, layout, host, openScreen }: PluginPopoverProps) {
+  const styles = useMemo(() => createStyles(theme, layout.compact), [layout.compact, theme]);
+  const { data, error } = useReadyBeads(host.id, "always");
+
+  if (!data) {
+    return (
+      <View style={styles.state}>
+        {error ? null : <ActivityIndicator color={theme.colors.accent} />}
+        <Text style={styles.note}>
+          {error ? `Could not load Beads. ${errorMessage(error)}` : "Loading ready beads…"}
+        </Text>
+      </View>
+    );
+  }
+
+  const { empty, notices } = describeReadyBeads(data, error ? errorMessage(error) : null);
+
+  return (
+    <View style={styles.list}>
+      {empty ? <Text style={styles.note}>{empty}</Text> : null}
+      {data.groups.map(({ workspace, beads }) => (
+        <View key={workspace.id} style={styles.group}>
+          <View style={styles.groupHeading}>
+            <Text accessibilityRole="header" style={styles.workspace} numberOfLines={1}>
+              {workspace.name}
+            </Text>
+            <Text style={styles.project} numberOfLines={1}>
+              {workspace.projectDisplayName}
+            </Text>
+          </View>
+          {beads.map((bead) => (
+            <Pressable
+              key={bead.id}
+              accessibilityRole="button"
+              accessibilityLabel={`Open ${bead.id}: ${bead.title}. Priority P${bead.priority}.`}
+              onPress={() =>
+                openScreen({
+                  screenId: BEAD_SCREEN_ID,
+                  params: { workspace: workspace.id, bead: bead.id },
+                })
+              }
+              style={({ pressed }) => [styles.row, pressed && styles.pressed]}
+            >
+              <Text
+                style={[styles.priority, { color: priorityColor(bead.priority, theme.colors) }]}
+              >
+                P{bead.priority}
+              </Text>
+              <Text style={styles.id}>{bead.id}</Text>
+              <Text style={styles.title} numberOfLines={1}>
+                {bead.title}
+              </Text>
+            </Pressable>
+          ))}
+        </View>
+      ))}
+      {data.count > READY_LIST_LIMIT ? (
+        <Text style={styles.note}>
+          Showing {READY_LIST_LIMIT} of {data.count} ready beads.
+        </Text>
+      ) : null}
+      {notices.map((notice) => (
+        <Text key={notice} style={styles.note}>
+          {notice}
+        </Text>
+      ))}
+    </View>
+  );
+}
+
+function createStyles(theme: PluginPopoverProps["theme"], compact: boolean) {
+  return StyleSheet.create({
+    list: { gap: 12 },
+    state: { alignItems: "center", gap: 8, paddingVertical: 12 },
+    group: { gap: 2 },
+    groupHeading: {
+      flexDirection: "row",
+      alignItems: "baseline",
+      gap: 6,
+      paddingHorizontal: 6,
+      paddingBottom: 2,
+    },
+    workspace: { flexShrink: 1, color: theme.colors.foreground, fontSize: 12, fontWeight: "700" },
+    project: { flexShrink: 1, color: theme.colors.foregroundMuted, fontSize: 11 },
+    row: {
+      minHeight: compact ? 44 : 32,
+      flexDirection: "row",
+      alignItems: "center",
+      gap: 8,
+      paddingHorizontal: 6,
+      borderRadius: 6,
+    },
+    pressed: { backgroundColor: theme.colors.surface2 },
+    priority: { fontSize: 11, fontWeight: "800" },
+    id: { color: theme.colors.foregroundMuted, fontSize: 11, fontFamily: ID_FONT_FAMILY },
+    title: { flex: 1, minWidth: 0, color: theme.colors.foreground, fontSize: 13 },
+    note: { color: theme.colors.foregroundMuted, fontSize: 12, lineHeight: 17 },
+  });
+}

package/client/ready-scan.ts

@@ -0,0 +1,78 @@
+import type { QueryClient, QueryKey } from "@tanstack/react-query";
+import type { BeadsSnapshot } from "../shared/beads";
+import {
+  beadsSnapshotQueryKey,
+  type ReadyBeadsSummary,
+  type ReadyBeadsWorkspace,
+  summarizeReadyBeads,
+} from "./beads-view";
+
+/** How many ready beads the popover lists; the sidebar count covers all of them. */
+export const READY_LIST_LIMIT = 10;
+/** The panel's polling interval: a snapshot an open panel just read is reused, not refetched. */
+const SNAPSHOT_FRESH_MS = 10_000;
+/** A workspace without Beads is rechecked this rarely: it seldom changes and each check runs bd. */
+const NO_BEADS_FRESH_MS = 5 * 60_000;
+/** How long a successful read vouches for the database a workspace reads. */
+const DATABASE_MEMORY_MS = 10 * 60_000;
+
+/**
+ * The database a workspace was last confirmed to read, or null when nothing vouches for it. The
+ * cache cannot decide this on its own: `gcTime` only drops queries nobody observes, and an open
+ * panel keeps a failing query's old data indefinitely. So the data must not be invalidated (a
+ * failed refresh keeps the old data but flags it) and must be recent.
+ */
+function confirmedDatabase(queryClient: QueryClient, queryKey: QueryKey): string | null {
+  const state = queryClient.getQueryState<BeadsSnapshot>(queryKey);
+  if (!state || state.isInvalidated) return null;
+  if (Date.now() - state.dataUpdatedAt > DATABASE_MEMORY_MS) return null;
+  return state.data?.databaseId ?? null;
+}
+
+export interface ReadyBeadsScan {
+  hostId: string;
+  /** Stops the scan from starting more workspace reads once its query is cancelled. */
+  signal: AbortSignal;
+  queryClient: QueryClient;
+  listWorkspaces(): Promise<readonly ReadyBeadsWorkspace[]>;
+  loadSnapshot(input: { workspaceId: string }): Promise<BeadsSnapshot>;
+}
+
+/**
+ * Reads each workspace's Beads snapshot through the cache the panel polls, and summarizes the
+ * ready beads. A workspace is skipped only when it is confirmed to read a database that this scan
+ * has read, so the first scan reads every workspace and learns which ones share a database (git
+ * worktrees do), and later scans read each database once. A workspace that cannot be read counts
+ * as failed.
+ */
+export async function scanReadyBeads({
+  hostId,
+  signal,
+  queryClient,
+  listWorkspaces,
+  loadSnapshot,
+}: ReadyBeadsScan): Promise<ReadyBeadsSummary> {
+  const readDatabases = new Set<string>();
+  const loaded: { workspace: ReadyBeadsWorkspace; snapshot: BeadsSnapshot | null }[] = [];
+  // ponytail: first page of the workspace list (up to 200), read one at a time so bd load stays
+  // flat. Add a small pool if the count lags on hosts with many Beads projects.
+  for (const workspace of await listWorkspaces()) {
+    if (signal.aborted) throw new Error("The ready beads scan was cancelled.");
+    const queryKey = beadsSnapshotQueryKey(hostId, workspace.id);
+    const knownDatabase = confirmedDatabase(queryClient, queryKey);
+    if (knownDatabase && readDatabases.has(knownDatabase)) continue;
+    // fetchQuery, not query(): the host app's query-core (5.90) has no query().
+    const snapshot = await queryClient
+      .fetchQuery({
+        queryKey,
+        queryFn: () => loadSnapshot({ workspaceId: workspace.id }),
+        staleTime: (query) =>
+          query.state.data?.state === "not_initialized" ? NO_BEADS_FRESH_MS : SNAPSHOT_FRESH_MS,
+        gcTime: DATABASE_MEMORY_MS, // storage cleanup only; confirmedDatabase enforces the age
+      })
+      .catch(() => null);
+    if (snapshot?.databaseId) readDatabases.add(snapshot.databaseId);
+    loaded.push({ workspace, snapshot });
+  }
+  return summarizeReadyBeads(loaded, READY_LIST_LIMIT);
+}

package/index.client.tsx

@@ -1,5 +1,7 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
-import { PaseoBeads } from "./client/paseo-beads";
+import { BEAD_SCREEN_ID, parseBeadScreenParams } from "./client/beads-view";
+import { BeadScreen, PaseoBeads } from "./client/paseo-beads";
+import { ReadyBeadsItem } from "./client/ready-beads";
 
 export default function contribute(client: PluginClientContext) {
   const removePanel = client.addWorkspacePanel({
@@ -30,8 +32,25 @@ export default function contribute(client: PluginClientContext) {
       openPanel("beads");
     },
   });
+  // Paseo 0.11 added screens and sidebar header items. 0.9 and 0.10 keep the panel and commands.
+  const removeReadyBeads =
+    typeof client.addScreen === "function" && typeof client.addSidebarHeaderItem === "function"
+      ? [
+          client.addScreen({
+            id: BEAD_SCREEN_ID,
+            title: (params) => parseBeadScreenParams(params)?.issueId ?? "Bead",
+            Component: BeadScreen,
+          }),
+          client.addSidebarHeaderItem({
+            id: "ready-beads",
+            title: "Ready beads",
+            Component: ReadyBeadsItem,
+          }),
+        ]
+      : [];
 
   return () => {
+    for (const remove of removeReadyBeads) remove();
     removeAgentCommand();
     removeWorkspaceCommand();
     removePanel();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-beads",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "A dependency-aware Beads work queue for each Paseo workspace.",
   "license": "MIT",
@@ -49,10 +49,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.10",
-    "@getpaseo/cli": "0.10.1",
-    "@getpaseo/client": "0.10.1",
-    "@getpaseo/plugin": "0.10.1",
-    "@getpaseo/protocol": "0.10.1",
+    "@getpaseo/cli": "0.11.0-beta.3",
+    "@getpaseo/client": "0.11.0-beta.3",
+    "@getpaseo/plugin": "0.11.0-beta.3",
+    "@getpaseo/protocol": "0.11.0-beta.3",
     "@tanstack/react-query": "^5.102.3",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.18",

package/paseo-plugin.json

@@ -1,5 +1,5 @@
 {
   "id": "paseo-beads",
   "description": "A dependency-aware Beads work queue for each Paseo workspace.",
-  "requirements": { "paseo": "^0.9.0 || ^0.10.0" }
+  "requirements": { "paseo": "^0.9.0 || ^0.10.0 || ^0.11.0" }
 }

package/server/beads.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
@@ -18,11 +19,16 @@ const execFileAsync = promisify(execFile);
 const COMMAND_TIMEOUT_MS = 10_000;
 const MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
 const MAX_DIAGNOSTIC_CHARS = 512;
+const MAX_PATH_CHARS = 4_096;
 
 const rawIdentifierSchema = z.string().max(BEADS_LIMITS.identifier);
 const rawTitleSchema = z.string().max(BEADS_LIMITS.title);
 const rawStatusOrTypeSchema = z.string().max(BEADS_LIMITS.statusOrType);
 const rawTimestampSchema = z.string().max(BEADS_LIMITS.timestamp).datetime();
+const RawDatabaseLocationSchema = z.object({
+  database_path: z.string().min(1).max(MAX_PATH_CHARS).optional(),
+  path: z.string().min(1).max(MAX_PATH_CHARS).optional(),
+});
 
 const RawBeadSummarySchema = z.object({
   id: rawIdentifierSchema,
@@ -141,6 +147,24 @@ async function loadReadyIds(
   return new Set(RawReadyIssueListSchema.parse(result).map(({ id }) => id));
 }
 
+/**
+ * Names the database `bd` resolves for a directory, so workspaces that share one (git worktrees,
+ * redirects) can be counted once. The ID is a digest, so no path leaves the daemon. Best effort:
+ * an older `bd` or a failing `bd where` leaves it null, and the list and ready queries still decide
+ * the snapshot's state.
+ */
+async function loadDatabaseId(directory: string, runner: BdCommandRunner): Promise<string | null> {
+  try {
+    const location = RawDatabaseLocationSchema.parse(
+      await runBd(directory, ["where", "--json"], runner),
+    );
+    const database = location.database_path ?? location.path;
+    return database ? createHash("sha256").update(database).digest("hex").slice(0, 16) : null;
+  } catch {
+    return null;
+  }
+}
+
 function errorText(error: unknown): string {
   if (!(error instanceof Error)) {
     return typeof error === "string"
@@ -249,6 +273,7 @@ function unavailableSnapshot(state: "not_initialized" | "bd_unavailable") {
     issues: [],
     truncated: false,
     refreshedAt: new Date().toISOString(),
+    databaseId: null,
     message:
       state === "bd_unavailable"
         ? "The bd CLI is not available on this Paseo host."
@@ -264,13 +289,14 @@ export async function handleGetWorkspaceBeads(
   const directory = await resolveWorkspaceDirectory(workspaceId, context);
 
   try {
-    const [listJson, readyIds] = await Promise.all([
+    const [listJson, readyIds, databaseId] = await Promise.all([
       runBd(
         directory,
         ["list", "--json", "--sort", "priority", "--limit", String(BEADS_LIMITS.rawIssueList)],
         runner,
       ),
       loadReadyIds(directory, runner),
+      loadDatabaseId(directory, runner),
     ]);
     const listed = RawIssueListSchema.parse(listJson);
     const truncated = listed.length > BEADS_LIMITS.issueList;
@@ -282,6 +308,7 @@ export async function handleGetWorkspaceBeads(
       truncated,
       refreshedAt: new Date().toISOString(),
       message: null,
+      databaseId,
     });
   } catch (error) {
     if (isBdUnavailable(error)) return unavailableSnapshot("bd_unavailable");

package/shared/beads.ts

@@ -62,6 +62,11 @@ export const BeadsSnapshotSchema = z.object({
   truncated: z.boolean(),
   refreshedAt: timestampSchema,
   message: z.string().max(BEADS_LIMITS.publicMessage).nullable(),
+  /**
+   * Opaque ID of the Beads database behind the snapshot. Workspaces that share one database, such
+   * as git worktrees, report the same ID. Null or absent when `bd` could not say.
+   */
+  databaseId: identifierSchema.nullish(),
 });
 
 export type BeadSummary = z.infer<typeof BeadSummarySchema>;