paseo-bm-plugin 0.0.0-placeholder.0

package/client/waiting-pills.tsx

@@ -0,0 +1,201 @@
+/**
+ * "Questions waiting" pills above a Manager's chat (delta
+ * 20260918d-card-replies §4.8, REQ-059 j; owner decision Q15 b).
+ *
+ * One composer pill per Worker whose latest report asks the user something,
+ * next to Paseo's own pills. Pressing it opens a popover with that report's
+ * card, so the questions are answered there, through the card's own Reply
+ * path. Paseo 0.8 gives a plugin no way to scroll the chat to a card, which is
+ * why a popover stands in for scrolling.
+ *
+ * A Manager whose chat has fallback incidents waiting for the user's decision
+ * gets one more pill that counts them; its popover shows their cards, with
+ * the buttons (delta 20260921 §4.4.6).
+ *
+ * The list comes from `chat.waiting`, read at registration and every
+ * `WAITING_POLL_MS`. A failed read keeps the pills as they are.
+ *
+ * Each pill keeps ONE popover component for its whole life, and that component
+ * reads the pill's newest report (or incidents) from a small store: redrawing a
+ * pill after a refresh must not remount an open popover and lose a Reply being
+ * typed (delta 20260918f F13).
+ */
+import type {
+  PluginButton,
+  PluginButtonContentProps,
+  PluginButtonRegistration,
+  PluginClientContext,
+} from "@getpaseo/plugin/client";
+import { useSyncExternalStore, type ComponentType } from "react";
+import { View } from "react-native";
+import { chatWaitingRpc, type FallbackIncident, type WaitingWorker } from "../shared/contracts";
+import { ChatCardView } from "./chat-card";
+import { CHAT_CARD_KIND, CHAT_CARD_VERSION, fallbackCardOfIncident, toChatCard } from "./chat-cards";
+import {
+  FALLBACK_PILL_ICON,
+  WAITING_PILL_ICON,
+  WAITING_POLL_MS,
+  pillChatOf,
+  planPills,
+  type ComposerPill,
+} from "./waiting-pills-model";
+
+/** The newest state of each shown pill, by pill id; one per loaded client bundle. */
+const entries = new Map<string, ComposerPill>();
+const listeners = new Set<() => void>();
+
+function setEntry(pillId: string, pill: ComposerPill | undefined): void {
+  if (pill === undefined) entries.delete(pillId);
+  else entries.set(pillId, pill);
+  for (const listener of listeners) listener();
+}
+
+function subscribeEntries(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** The report a pill's popover shows now, if the pill is shown. */
+export function waitingEntryOf(pillId: string): WaitingWorker | undefined {
+  const pill = entries.get(pillId);
+  return pill?.kind === "questions" ? pill.entry : undefined;
+}
+
+/** The incidents a fallback pill's popover shows now, if the pill is shown. */
+export function fallbackEntriesOf(pillId: string): FallbackIncident[] | undefined {
+  const pill = entries.get(pillId);
+  return pill?.kind === "fallback" ? pill.incidents : undefined;
+}
+
+/**
+ * The popover of one pill: the card of its newest report, or the card of each
+ * pending incident, whose buttons read and act on `fallback.incidents`. Made
+ * once per pill.
+ */
+function contentFor(pillId: string): ComponentType<PluginButtonContentProps> {
+  return function WaitingCard({ theme, layout, host }: PluginButtonContentProps) {
+    const read = () => entries.get(pillId);
+    const pill = useSyncExternalStore(subscribeEntries, read, read);
+    if (pill === undefined) return null;
+    if (pill.kind === "fallback") {
+      return (
+        <View style={{ gap: 8 }}>
+          {pill.incidents.map((incident) => (
+            <ChatCardView
+              key={incident.id}
+              theme={theme}
+              layout={layout}
+              host={host}
+              agentId={pill.managerId}
+              item={{ type: "plugin", kind: CHAT_CARD_KIND, version: CHAT_CARD_VERSION, data: fallbackCardOfIncident(incident) }}
+              timestamp={new Date(incident.detectedAt)}
+            />
+          ))}
+        </View>
+      );
+    }
+    const entry = pill.entry;
+    const card = toChatCard({ type: "user_message", text: entry.text }, "complete");
+    if (card === undefined) return null;
+    return (
+      <ChatCardView
+        theme={theme}
+        layout={layout}
+        host={host}
+        agentId={entry.managerId}
+        item={{ type: "plugin", kind: CHAT_CARD_KIND, version: CHAT_CARD_VERSION, data: card }}
+        timestamp={entry.at === null ? new Date() : new Date(entry.at)}
+      />
+    );
+  };
+}
+
+function buttonOf(pill: ComposerPill, Content: ComponentType<PluginButtonContentProps>): PluginButton {
+  return {
+    title: pill.title,
+    label: pill.label,
+    icon: pill.kind === "fallback" ? FALLBACK_PILL_ICON : WAITING_PILL_ICON,
+    behavior: { kind: "popover", Content },
+  };
+}
+
+/** Starts the pills; returns the cleanup that stops reading and removes them all. */
+export function registerWaitingPills(client: PluginClientContext): () => void {
+  const shown = new Map<
+    string,
+    {
+      key: string;
+      managerId: string;
+      workspaceId: string;
+      Content: ComponentType<PluginButtonContentProps>;
+      registration: PluginButtonRegistration;
+    }
+  >();
+  let pending = false;
+  let stopped = false;
+
+  const refresh = async () => {
+    if (pending || stopped) return;
+    pending = true;
+    try {
+      // `fallback` is absent from a server built before it.
+      const { waiting, fallback = [] } = await client.rpc(chatWaitingRpc, {});
+      if (stopped) return;
+      const plan = planPills(new Map([...shown].map(([id, pill]) => [id, pill.key])), waiting, fallback);
+      for (const id of plan.remove) {
+        shown.get(id)?.registration.remove();
+        shown.delete(id);
+        setEntry(id, undefined);
+      }
+      const added = [...plan.add];
+      for (const pill of plan.update) {
+        const current = shown.get(pill.id);
+        if (current === undefined) continue;
+        const chat = pillChatOf(pill);
+        // A registration cannot move to another chat: re-add it there instead.
+        if (current.managerId !== chat.managerId || current.workspaceId !== chat.workspaceId) {
+          current.registration.remove();
+          shown.delete(pill.id);
+          added.push(pill);
+          continue;
+        }
+        setEntry(pill.id, pill);
+        current.registration.update(buttonOf(pill, current.Content));
+        current.key = pill.key;
+      }
+      for (const pill of added) {
+        const Content = contentFor(pill.id);
+        const chat = pillChatOf(pill);
+        setEntry(pill.id, pill);
+        const registration = client.addComposerPill({
+          id: pill.id,
+          workspaceId: chat.workspaceId,
+          agentId: chat.managerId,
+          button: buttonOf(pill, Content),
+        });
+        shown.set(pill.id, { key: pill.key, managerId: chat.managerId, workspaceId: chat.workspaceId, Content, registration });
+      }
+    } catch {
+      // A failed read keeps the pills as they are: better a pill one period
+      // late than pills that flicker whenever the daemon is slow.
+    } finally {
+      pending = false;
+    }
+  };
+
+  void refresh();
+  const timer = setInterval(() => void refresh(), WAITING_POLL_MS);
+  // Node (tests) would otherwise stay alive for the timer; hosts without unref ignore this.
+  (timer as { unref?: () => void }).unref?.();
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+    for (const [id, pill] of shown) {
+      pill.registration.remove();
+      setEntry(id, undefined);
+    }
+    shown.clear();
+  };
+}

package/index.client.tsx

@@ -0,0 +1,232 @@
+import type { PluginClientContext, PluginWorkspaceCommandContext } from "@getpaseo/plugin/client";
+import {
+  LAUNCHER_ICON,
+  LAUNCHER_SURFACE_ID,
+  selectFromCommandCenter,
+} from "./client/launch-manager";
+import { agentsStopAllRpc, managerEnsureRpc } from "./shared/contracts";
+import { NEW_REQUEST_MARKER } from "./shared/new-request";
+import { ManagerLauncherSurface } from "./client/launcher";
+import { AGENT_TREE_ICON, AGENT_TREE_PANEL_ID } from "./client/agent-tree";
+import { AgentTreePanel } from "./client/tree";
+import { DASHBOARD_ICON } from "./client/dashboard-model";
+import { BEADS_TAB_PANEL_ID, launcherNotices, selectDashboardFromCommandCenter } from "./client/dashboard-view";
+import { DashboardSettingsScreen, SETTINGS_ICON, SETTINGS_SCREEN_ID } from "./client/settings";
+import { CHAT_CARD_KIND, CHAT_CARD_VERSION, chatCardSchema, toChatCard } from "./client/chat-cards";
+import { ChatCardView } from "./client/chat-card";
+import { ChatBeadsPanel } from "./client/bead-chips";
+import { BeadsTabPanel } from "./client/beads-tab";
+import { registerBeadsHeaderButtons } from "./client/beads-header-button";
+import { registerWaitingPills } from "./client/waiting-pills";
+
+/** A chat item as a paseo-bm card, or nothing (the item stays Paseo's). */
+function chatCardItems(item: { type: string }, phase: "streaming" | "complete") {
+  const card = toChatCard(item, phase);
+  return card === undefined
+    ? undefined
+    : { items: [{ type: "plugin" as const, kind: CHAT_CARD_KIND, version: CHAT_CARD_VERSION, data: card }] };
+}
+
+// ---------------------------------------------------------------------------
+// Slash commands (delta 20260917e §4.4).
+// ---------------------------------------------------------------------------
+
+/** What Paseo hands a slash command: the workspace context plus the typed text. */
+type WorkspaceCommand = PluginWorkspaceCommandContext & { args: string };
+
+/**
+ * `/bm-worker-new <request>`.
+ *
+ * A typing shortcut, not a second way to create a Worker (owner decision Q24):
+ * the request goes to the Manager, and the Manager keeps doing what it always
+ * does — mint the `requestId`, size the work, create the Worker, report back.
+ * Creating a Worker here would leave those steps to nobody.
+ *
+ * `paseo.agents.ref().send()` is the path the app's own composer uses, so the
+ * request is recorded as a real user message (verified fact P2) and none of the
+ * three role prompts has to learn about this command.
+ */
+async function runWorkerNew(context: WorkspaceCommand): Promise<void> {
+  const request = context.args.trim();
+  // `manager.ensure` is the same call the launcher button makes: it finds this
+  // workspace's live Manager or starts one, and de-duplicates server-side.
+  const { agentId } = await context.rpc(managerEnsureRpc, { workspaceId: context.workspace.id });
+  // Verbatim: anything we prefixed would be quoted back at the user as their
+  // own words, and would land in the trace store as part of the request. No
+  // args sends nothing at all, because an empty message would force the Manager
+  // to invent a request, which its own rules forbid.
+  // The flag line tells the Manager this is NEW work, not a follow-up. Without
+  // it the Manager applies its own rule -- a message while a request is live is
+  // a follow-up -- and hands the words to the Worker already busy, which is the
+  // opposite of what this command is for (delta 20260917f §2 lỗi A).
+  if (request !== "") {
+    await context.paseo.agents.ref(agentId).send(`${NEW_REQUEST_MARKER}\n${request}`);
+  }
+  // Either way the chat opens, so the user can keep typing into it. That goes
+  // through the Command Center hand-off, because a command context has no
+  // `navigation.openAgent` — only a surface does. The surface calls
+  // `manager.ensure` a second time on the way; that call is idempotent and
+  // returns the Manager this one just ensured.
+  selectFromCommandCenter(context);
+}
+
+/** English plural for a count: `1 Worker`, `0 Workers`, `2 Workers`. */
+function counted(value: number, noun: string): string {
+  return `${value} ${noun}${value === 1 ? "" : "s"}`;
+}
+
+/**
+ * What the user is told after `/bm-worker-stop-all`.
+ *
+ * Every word is weighed against verified fact P4: Paseo gives a plugin no way
+ * to cancel an agent, so the command delivers a notice and nothing more.
+ * "Asked … to stop" is what happened; "stopped" would be a promise the product
+ * cannot keep, and a user who believes it will not go back and check.
+ */
+function stopAllSummary(result: { workers: number; reviewers: number; skipped: number }): string {
+  return (
+    `Asked ${counted(result.workers, "Worker")} and ${counted(result.reviewers, "Reviewer")} ` +
+    `in this workspace to stop; skipped ${counted(result.skipped, "agent")} (archived, or not running). ` +
+    `Paseo cannot cancel an agent from a plugin, so each one stops itself once it reads the notice.`
+  );
+}
+
+/**
+ * `/bm-worker-stop-all`. The server picks the targets and sends the notices;
+ * this only reports the counts it answers with.
+ */
+async function runWorkerStopAll(context: WorkspaceCommand): Promise<void> {
+  const result = await context.rpc(agentsStopAllRpc, { workspaceId: context.workspace.id });
+  // Paseo 0.8 gives a slash command no report channel: the only thing the
+  // composer ever shows is a REJECTION, turned into an error toast. Reporting a
+  // success that way would paint "Asked 2 Workers to stop" in the colour of a
+  // failure. So the summary is posted to the Beads Manager surface, which draws
+  // it as an ordinary notice. Staying silent is not an option either: the user
+  // must learn the agents were ASKED, not killed (P4).
+  launcherNotices.put(stopAllSummary(result));
+  context.openSurface(LAUNCHER_SURFACE_ID);
+}
+
+/**
+ * Client entry of the paseo-bm plugin (design §2.4).
+ *
+ * WP-211 adds the Dashboard to that same surface (Q-036): a "Dashboard" button
+ * per workspace, a workspace Command Center item that queues a workspace and
+ * opens the surface, and a plugin settings screen for the trace-store warning
+ * threshold.
+ *
+ * WP-113 registers the "Beads Manager" surface, its sidebar item and the
+ * workspace Command Center item; both open the Manager through
+ * `manager.ensure`. It also registers the read-only "Beads agents" workspace
+ * panel (agent tree + role configuration).
+ *
+ * It also turns messages between the Manager, Workers and Reviewers into chat
+ * cards (delta 20260916-chat-cards), registers the two slash commands of
+ * delta 20260917e §4.4, and adds the "Beads" tab that Paseo lists in the "+"
+ * menu of every workspace (delta 20260918e §4.1).
+ *
+ * This entry must never import from `server/`: that is a compile error.
+ *
+ * Declared as a hoisted `export default function`, not `const` + `export
+ * default`: Paseo 0.8 rewrites esbuild's export getters into eager copies
+ * (makeHermesInteropEager), so a late-bound default export is copied while
+ * still undefined and the daemon refuses the plugin ("must default export a
+ * function"). Guarded by test/plugin-bundle-cjs.test.ts.
+ */
+export default function contribute(client: PluginClientContext): () => void {
+  // Register the surface before the sidebar item that points at it.
+  const removers = [
+    client.addSurface(LAUNCHER_SURFACE_ID, ManagerLauncherSurface),
+    client.addSidebarItem({
+      id: LAUNCHER_SURFACE_ID,
+      title: "Beads Manager",
+      icon: LAUNCHER_ICON,
+      surface: LAUNCHER_SURFACE_ID,
+    }),
+    client.addCommandCenterItem({
+      id: "open-beads-manager",
+      title: "Open Beads Manager",
+      icon: LAUNCHER_ICON,
+      keywords: ["beads", "manager", "paseo-bm"],
+      context: "workspace",
+      onSelect: (context) => selectFromCommandCenter(context),
+    }),
+    client.addCommandCenterItem({
+      id: "open-beads-dashboard",
+      title: "Open Beads Metric",
+      icon: DASHBOARD_ICON,
+      keywords: ["beads", "metric", "dashboard", "traces", "paseo-bm"],
+      context: "workspace",
+      onSelect: (context) => selectDashboardFromCommandCenter(context, LAUNCHER_SURFACE_ID),
+    }),
+    client.addSlashCommand({
+      name: "bm-worker-new",
+      description: "Give Beads Manager a new request; it creates the Worker",
+      argumentHint: "<what you want done>",
+      context: "workspace",
+      onSubmit: (context) => runWorkerNew(context),
+    }),
+    client.addSlashCommand({
+      name: "bm-worker-stop-all",
+      description: "Ask every running Beads Worker and Reviewer in this workspace to stop",
+      argumentHint: "",
+      context: "workspace",
+      onSubmit: (context) => runWorkerStopAll(context),
+    }),
+    client.addSettingsScreen({
+      id: SETTINGS_SCREEN_ID,
+      title: "Beads Dashboard",
+      icon: SETTINGS_ICON,
+      Component: DashboardSettingsScreen,
+    }),
+    // Messages between the Manager, Workers and Reviewers as cards
+    // (delta 20260916-chat-cards). Only paseo-bm's own messages are changed.
+    client.addTimelineTransformer({
+      id: "bm-chat-received",
+      query: { itemType: "user_message" },
+      transform: ({ item, phase }) => chatCardItems(item, phase),
+    }),
+    client.addTimelineTransformer({
+      id: "bm-chat-sent",
+      query: { itemType: "assistant_message" },
+      transform: ({ item, phase }) => chatCardItems(item, phase),
+    }),
+    client.addTimelineRenderer({
+      kind: CHAT_CARD_KIND,
+      version: CHAT_CARD_VERSION,
+      schema: chatCardSchema,
+      Component: ChatCardView,
+    }),
+    client.addWorkspacePanel({
+      id: "bm-chat-beads",
+      title: "Beads in this chat",
+      icon: "ListChecks",
+      context: "agent",
+      Component: ChatBeadsPanel,
+    }),
+    // Before "Beads agents", so it leads paseo-bm's entries in the "+" menu.
+    // No `locations`: Paseo's default, ["workspace"], is the tab bar.
+    client.addWorkspacePanel({
+      id: BEADS_TAB_PANEL_ID,
+      title: "Beads",
+      icon: "ListChecks",
+      context: "workspace",
+      Component: BeadsTabPanel,
+    }),
+    // The same tab from a button on every workspace header: Paseo 0.8's mobile
+    // app has no "+" menu (delta 20260918e §4.6).
+    registerBeadsHeaderButtons(client),
+    client.addWorkspacePanel({
+      id: AGENT_TREE_PANEL_ID,
+      title: "Beads agents",
+      icon: AGENT_TREE_ICON,
+      context: "workspace",
+      Component: AgentTreePanel,
+    }),
+    // A pill per Worker waiting for the user's answer (delta 20260918d §4.8).
+    registerWaitingPills(client),
+  ];
+  return () => {
+    for (const remove of removers) void remove();
+  };
+}

package/index.server.ts

@@ -0,0 +1,168 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { MANAGER_INSTRUCTIONS } from "./server/manager-instructions";
+import { ensureManager, listWorkspaceAgents } from "./server/manager";
+import { registerCollector } from "./server/collector";
+import { checkReviewBudget, type BudgetOverrun, type BudgetPaseo } from "./server/review-budget";
+import { registerDashboardRpcs } from "./server/dashboard-rpc";
+import { registerRoleHook } from "./server/role-hook";
+import { describeRoles } from "./server/roles";
+import { registerStopPropagation } from "./server/stop-propagation";
+import { registerAgentLabels } from "./server/agent-labels";
+import { registerFallbackRpcs } from "./server/fallback-rpc";
+import { registerFallbackDetection, replacementsFor } from "./server/fallback-state";
+import { createManagerSwitch } from "./server/fallback-manager";
+import { createReviewerResend, createReviewerSwitch } from "./server/fallback-reviewer";
+import type { FallbackAction } from "./server/fallback-rpc";
+import { createWorkerSwitch } from "./server/fallback-switch";
+import { createFallbackWaiter } from "./server/fallback-wait";
+import { registerFormatCheck } from "./server/format-check";
+import { registerNoticeQueue } from "./server/notice-queue";
+import { currentInstructions } from "./server/role-extras";
+import { registerSetupRpcs } from "./server/setup-rpc";
+import { registerRoleSettingsRpcs } from "./server/role-settings-rpc";
+import { registerChatRpcs } from "./server/chat-rpc";
+import { agentsListRpc, managerEnsureRpc, rolesDescribeRpc, type FallbackIncident } from "./shared/contracts";
+import { dashboardSettings } from "./shared/settings";
+
+/**
+ * Text of `roles/manager.md`.
+ *
+ * Embedded at build time (scripts/generate-role-instructions.mjs), never read
+ * from disk: Paseo 0.8 compiles this entry into a CommonJS bundle and runs it
+ * in a forked worker without a cwd, so this code has no way to know where its
+ * payload lives (bm-dnc). Nothing in the server entry may depend on file
+ * locations at run time.
+ */
+export function readManagerInstructions(): Promise<string> {
+  return Promise.resolve(MANAGER_INSTRUCTIONS);
+}
+
+/**
+ * Server entry of the paseo-bm plugin.
+ *
+ * WP-112 registers `manager.ensure`, `agents.list` and `roles.describe`. All
+ * three only read or create; there is deliberately no RPC that deletes or archives agents:
+ * their lifecycle belongs to the user (ADR-005).
+ *
+ * WP-208 and WP-210 add the Dashboard RPCs (`beads.stats`, `traces.delete`);
+ * `traces.delete` is the only handler in the plugin that removes anything, and
+ * it only ever removes paseo-bm's own trace records.
+ *
+ * WP-205 adds the trace collector: `agent.turn_started` and `agent.turn_ended`
+ * hooks that write one record per `bm-*` agent turn into the trace store, so the
+ * Dashboard has history that outlives the agents themselves (ADR-007). It
+ * resolves the store itself from the hook context and can never throw into an
+ * agent turn.
+ *
+ * It also registers a `before("agent.create")` hook that puts the role
+ * instructions into the system prompt of every `bm-manager`, `bm-worker` and
+ * `bm-reviewer` agent, whoever creates it: Paseo's `create_agent` tool has no
+ * system-prompt parameter (bm-hld). It also registers an `on("agent.turn_ended")`
+ * hook that sends a stop notice to the running Reviewers of a Worker the user
+ * stopped (bm-wq6, REQ-026f). The returned cleanup removes every hook.
+ *
+ * This entry must never import from `client/`: that is a compile error.
+ *
+ * Declared as a hoisted `export default function`, not `const` + `export
+ * default`: Paseo 0.8 rewrites esbuild's export getters into eager copies
+ * (makeHermesInteropEager), so a late-bound default export is copied while
+ * still undefined and the daemon refuses the plugin ("must default export a
+ * function"). Guarded by test/plugin-bundle-cjs.test.ts.
+ */
+export default function contribute(server: PluginServerContext): () => void {
+  server.handle(managerEnsureRpc, async (input, { paseo }) => {
+    const result = await ensureManager(input, {
+      paseo,
+      // The base plus the user's additions from the Setup screen, when any.
+      readInstructions: () => currentInstructions("manager", paseo),
+    });
+    if (result.otherManagerIds.length > 0) {
+      console.warn(
+        `[paseo-bm] workspace ${input.workspaceId} has ${result.otherManagerIds.length + 1} live Managers; using ${result.agentId} (labelled Managers first, then the newest). Left untouched: ${result.otherManagerIds.join(", ")}.`,
+      );
+    }
+    if (result.modeNotice !== null) console.warn(`[paseo-bm] ${result.modeNotice}`);
+    if (result.toolsNotice !== null) console.warn(`[paseo-bm] ${result.toolsNotice}`);
+    return result;
+  });
+  // Without this the Dashboard's settings screen cannot read or save anything:
+  // `useSettings` on the client calls `settings.paseo-bm.read`, an RPC the HOST
+  // only contributes once the server has declared the definition. The owner's
+  // daemon log carried eight `Plugin paseo-bm does not contribute RPC
+  // settings.paseo-bm.read` errors because this one line was missing
+  // (bm-settings-rpc-stgv).
+  server.registerSettings(dashboardSettings);
+  server.handle(agentsListRpc, async (input, { paseo }) => listWorkspaceAgents(input, { paseo, replacements: await replacementsFor(paseo) }));
+  server.handle(rolesDescribeRpc, (_input, { paseo }) => describeRoles({ paseo }));
+  registerDashboardRpcs(server, {
+    ensureManager: async (workspaceId, paseo) => {
+      const result = await ensureManager({ workspaceId }, { paseo: paseo as never, readInstructions: () => currentInstructions("manager", paseo) });
+      // This path shows no launcher notice, so the log is the only place a mode problem surfaces.
+      if (result.modeNotice !== null) console.warn(`[paseo-bm] ${result.modeNotice}`);
+      if (result.toolsNotice !== null) console.warn(`[paseo-bm] ${result.toolsNotice}`);
+      return result;
+    },
+  });
+  registerSetupRpcs(server);
+  // delta 20260921 §4.3.2: the read-only data of Roles & models (`roles.settings`, `roles.options`).
+  registerRoleSettingsRpcs(server);
+  registerChatRpcs(server);
+  const removeRoleHook = registerRoleHook(server);
+  const removeStopPropagation = registerStopPropagation(server);
+  // delta 20260918g §4.5: a bm-* agent created without its bm.role label gets it.
+  const removeAgentLabels = registerAgentLabels(server);
+  // delta 20260921 §4.2.4 (F13): a plugin notice to an agent that may be running
+  // (BM-TOOLS, BM-SETTINGS, BM-FALLBACK) waits in memory for that agent's next
+  // turn end. The queue adds no hook of its own: it rides on the BM-FORMAT
+  // check's agent.turn_ended hook and runs after it, so a BM-FORMAT notice sent
+  // at the same turn end is never replaced by a queued one.
+  const noticeQueue = registerNoticeQueue(server);
+  // delta 20260918g §4.7: the sender of a BM-* block that breaks its template is told (BM-FORMAT).
+  const removeFormatCheck = registerFormatCheck(noticeQueue.host);
+  // delta 20260917c §4.7: the plugin counts the review budget and tells the
+  // Manager once per request; it never stops an agent.
+  const budgetTold = new Set<string>();
+  // Only an overrun found at a Worker's or Reviewer's turn end goes in here, and
+  // only what is in here may be sent at a Manager's turn end (review b2).
+  const budgetPending = new Map<string, BudgetOverrun>();
+  // delta 20260921 §4.4.4–§4.4.5: a Worker turn that ends on a provider-plan
+  // failure is classified and recorded as a fallback incident. Its own handler,
+  // not the collector's onRecorded, so detection never depends on the trace store.
+  // §4.4.9 (owner decision Q6 a): one timer per Wait click, set again after a
+  // reload at the first hook or fallback RPC that brings an SDK handle.
+  const fallbackWaiter = createFallbackWaiter();
+  const armWaits = (paseo: unknown) => void fallbackWaiter.ensureArmed(paseo);
+  const removeFallbackDetection = registerFallbackDetection(server, { onPaseo: armWaits });
+  // delta 20260921 §4.4.6: BM-FALLBACK to the Manager chat, fallback.incidents and fallback.act.
+  // "Switch": the plugin creates a replacement Worker (§4.4.7) or Manager
+  // (§4.5.2); for a Reviewer it tells the Worker how to create the
+  // replacement itself (§4.5.1).
+  const switches: Record<FallbackIncident["role"], FallbackAction> = {
+    worker: createWorkerSwitch(),
+    reviewer: createReviewerSwitch(),
+    manager: createManagerSwitch(),
+  };
+  const switchByRole: FallbackAction = (incident, paseo, deps) => switches[incident.role](incident, paseo, deps);
+  const removeFallbackNotices = registerFallbackRpcs(
+    server,
+    { switch: switchByRole, wait: fallbackWaiter.wait, resend: createReviewerResend() },
+    { onPaseo: armWaits },
+  );
+  const removeCollector = registerCollector(server, {
+    onRecorded: (event, { location, paseo }) =>
+      paseo === undefined
+        ? undefined
+        : checkReviewBudget(event, { location, paseo: paseo as BudgetPaseo, told: budgetTold, pending: budgetPending }),
+  });
+  return () => {
+    removeRoleHook();
+    removeStopPropagation();
+    removeAgentLabels();
+    removeFormatCheck();
+    noticeQueue.remove();
+    removeFallbackDetection();
+    removeFallbackNotices();
+    fallbackWaiter.clear();
+    removeCollector();
+  };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "paseo-bm-plugin",
+  "version": "0.0.0-placeholder.0",
+  "description": "Beads Management for Paseo — the plugin payload: the Metric, Beads and Setup screens plus the agent role instructions. Install with npx paseo-bm, which also registers the three agent roles.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hieunt286/paseo-bm.git",
+    "directory": "plugin"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "paseo-plugin.json",
+    "index.client.tsx",
+    "index.server.ts",
+    "client/",
+    "server/",
+    "shared/",
+    "roles/",
+    "tsconfig.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "paseo",
+    "paseo-plugin",
+    "beads"
+  ]
+}

package/paseo-plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "paseo-bm",
+  "requirements": {
+    "paseo": ">=0.8.0"
+  }
+}