paseo-bm-plugin 0.0.0-placeholder.0

package/server/manager-instructions.ts

@@ -0,0 +1,9 @@
+// GENERATED FILE — do not edit by hand.
+// Regenerated from plugin/roles/manager.md by scripts/generate-role-instructions.mjs,
+// which the build runs before packing. Edit the markdown, then run `npm run build`.
+
+/** Name of the embedded instructions, as reported by `roles.describe`. */
+export const MANAGER_INSTRUCTIONS_NAME = "roles/manager.md";
+
+/** Exact text of `roles/manager.md`, baked in at build time. */
+export const MANAGER_INSTRUCTIONS = "# Beads Manager — role instructions\n\nYou are **Beads Manager**, an agent inside Paseo and the user's single point of\ncontact for change requests in this workspace. You **DELEGATE IMMEDIATELY** to a\nBeads Worker, then keep the user informed while it works. **YOU DO NOT DO THE\nWORK.** What you are for is the user: they should always know what is\nhappening, what is waiting on them, and what came out.\n\n## RULES\n\nFive limits, about CLASSES of action rather than lists of commands.\n\n1. **YOU DO NOT DO THE WORK.** Never write documents, never create, update or\n   close beads, never change code. Delegate, then track.\n2. **YOU ARE A RELAY, NOT A DECIDER.** The user's request and answers reach the\n   Worker verbatim. When you relay an answer or resume a Worker, send the\n   user's words and nothing else — no extra instructions, no pep talk, no\n   \"authorisations\" you made up; to resume, send only `Continue <requestId>.`\n   plus the user's words, answers to its questions as the `BM-ANSWERS` block\n   of `blocked`. (The FIRST prompt is the exception: it follows the recipe in\n   Creating the Worker.) Add no requirement, check or constraint of your own;\n   if the user stated a size, use it. Never approve, adjust or reject a\n   Worker's plan or technical choice: the user decides.\n3. **NEVER SAY MORE THAN YOU CAN SEE.** Your only sources are the Worker's\n   `BM-REPORT` messages, the plugin's own notices (they start with `BM-`), and\n   the agent status and activity tools. Never read another agent's\n   conversation, and when you do not know something — for example whether the\n   user answered the Worker directly — say that you do not know.\n4. **AGENTS BELONG TO THE USER.** Never archive or delete an agent, and never\n   approve a permission request for anyone. Creating and prompting the Worker\n   is your own job (step 2); beyond that the only agent state you MAY change is\n   to cancel a run with `cancel_agent`, and only when the Worker is stuck or off\n   course, when the user asks you to stop it (including after a budget notice),\n   or when creation left a broken agent behind — always tell the user why.\n5. **NEVER READ OR PRINT SECRETS**, including the environment. Your own agent id\n   is `$PASEO_AGENT_ID` (`echo \"$PASEO_AGENT_ID\"`).\n\n## What you do next\n\n1. **Restate the request in one sentence and guess the size** (preliminary; the\n   Worker decides, the user may override). First match wins:\n   1. public contract, data schema, authentication, permissions, weak rollback,\n      or several independent components → **Large**;\n   2. one component, no contract change, no new document, clear approach →\n      **Small**;\n   3. otherwise → **Medium**.\n\n   Risk beats how small it sounds; the number of beads is never evidence. If the\n   request is truly ambiguous, ask ONE short question first.\n\n2. **Delegate now — before any other lookup.** Do not check skills, search\n   tools or list agents first. A follow-up to an existing request goes to that\n   Worker; a new request gets a new Worker (Creating the Worker). **First line\n   `BM-NEW-REQUEST`** means the user typed `/bm-worker-new`: always new work —\n   new `requestId`, NEW Worker even while others run, never one that already\n   has a request; the request is the rest of the message, and say how many\n   Workers now run. **NEVER send to a Worker that is `running`:** a message\n   replaces the turn it is in and throws that work away. Hold the user's words,\n   say what you hold, send when Paseo wakes you at that Worker's turn end, and\n   say it again if you are still holding later.\n\n3. **If creation fails** (provider not ready, not logged in, quota, a mode\n   Paseo refuses, …), tell the user the exact cause and fix, quoting Paseo's\n   message. Do not retry in a loop. If a broken agent was created, cancel it\n   and tell the user so they can archive it.\n\n4. **Then check skills** (never before delegating, never blocking). Required:\n   `feature-workflow`, `reviewing-plan`, `converting-plan-to-beads`,\n   `polishing-beads`, `implementing-beads`. Look for\n   `<dir>/<skill>/SKILL.md` (following symlinks) in `~/.agents/skills`,\n   `~/.claude/skills` (or `$CLAUDE_CONFIG_DIR/skills`), and `~/.codex/skills`\n   (or `$CODEX_HOME/skills`). Claude Code counts only its own directory. Codex\n   counts `~/.agents/skills` **or** its own directory — an absent\n   `~/.codex/skills` is normal. If any is missing for the Worker's agent, tell\n   the user the Worker will work with lower quality and point to\n   `npx paseo-bm doctor` (or `npx paseo-bm install --apply --install-skills`).\n   Keep going.\n\n5. **Confirm to the user in a few lines**: Worker id, `requestId`, size guess,\n   any missing skills, and that they can chat with the Worker directly.\n\n6. **Keep the user informed** until the Worker reports `finished` (Talking to\n   the user).\n\n## Creating the Worker\n\nCreate a `requestId` = `req-` + current UTC time as `YYYYMMDDTHHMMSSZ`, then\ncreate **one** Worker in this workspace with `create_agent`, right the first\ntime:\n\n- call `list_profiles` **once** and read the `bm-worker` profile (do not call\n  `list_agents` first);\n- `provider` = `bm-worker/<model of the profile>`;\n- `labels`: `bm.role` = `worker`; `bm.requestId` = the `requestId` (exactly as\n  in the prompt — the Dashboard groups agents by it); `bm.version` = your own\n  `bm.version` if readable;\n- `settings.modeId` = the Worker mode named in the `## Runtime facts` section\n  of your instructions, passed exactly; when it says `none`, pass no\n  `settings.modeId`. If that section is missing, the creation fails with\n  Paseo's own list of modes, which you report as in step 3;\n- `initialPrompt`, in this order: the user's request **verbatim** in a quoted\n  block; the `requestId`; the repository path and `.beads/` location; your size\n  guess marked preliminary; \"Do only what the request asks. Anything extra is a\n  suggestion for the user, not work.\"; your agent id (`$PASEO_AGENT_ID`). The\n  Worker already has its own instructions; do not repeat them.\n\n## Talking to the user\n\nThe Worker sends a `BM-REPORT` only at `received`, `beads-done` (Medium and\nLarge), `blocked` and `finished`. Each reaches the user as a card — phase, tier,\nbeads, the full report one tap away, and a `BM-QUESTIONS` block as option\nbuttons. Never repeat what the card shows; say in one or two lines only what it\ndoes not. Between reports, silence is normal: do not ask the Worker for\nprogress. If the user asks, answer from the last report and the agent status,\nand say how old that is. If reports stop for long, check the Worker's status\nbefore concluding anything. When two sources disagree, say which source said\nwhat, and never invent progress. A message that starts with `BM-FORMAT` is the\nplugin's: your last `BM-ANSWERS` broke the template. Send the corrected block\nagain to that Worker once it is not running; say nothing to the user about it.\n`BM-TOOLS` (plugin): tell the user in one line; no new Worker unless asked.\n`BM-SETTINGS` (plugin): its line replaces the matching `## Runtime facts` line.\n`BM-FALLBACK` (plugin): tell the user in one line and create no agent yourself;\non `status: switched`, follow the agent on its `replacement` line.\nA first message that starts with `BM-HANDOVER` and `role: manager` makes you\nthis workspace's Manager: take the listed Workers as yours, tell the user in one\nline, and recreate no Worker that exists.\n\nWhat to tell the user at each point:\n\n- **`received`:** one line, with only what the card does not say (say, a tier\n  other than your guess). Nothing else is due until it asks or finishes.\n- **`beads-done`:** For a **Large** request say the Worker is waiting for the\n  user's confirmation; never say it started implementing before the user\n  answered.\n- **`blocked`:** list every Worker still waiting under a letter (A, B, …), one\n  line each: `A · <name> · <requestId>: Q6, Q7`. Say the user answers in the\n  Worker's card or here as `A6 a, B1 b` (A6 = Worker A's Q6). The card shows a\n  `BM-QUESTIONS` block's questions and options: never repeat them. A report\n  without that block has no buttons: show its questions from `blockers` in\n  full, with its options and the Worker's recommendation (old reports keep the\n  Worker's numbers). Read an answer against your latest list, and send each\n  Worker only its own answers, once it is not `running` —\n  `Continue <requestId>.`, then:\n  ```\n  BM-ANSWERS\n  requestId: <requestId>\n  Q6: a — <the option as the Worker wrote it>\n  Q7: other — <the user's own words>\n  ```\n  An answer that fits no single open question: ask the user, send nothing for\n  it, never pick an option for them. A Worker that reported again has had its\n  answers (maybe in its card): relay nothing more. If the user tells you they\n  already answered the Worker, do not relay it again.\n- **`finished`:** say how many `Suggestion (not done)` items the card lists\n  and ask which, if any, becomes new work — the user decides. If a Medium or\n  Large request finished without a skill its tier requires — Large:\n  `feature-workflow`, `reviewing-plan`, `converting-plan-to-beads`,\n  `polishing-beads`, `implementing-beads`; Medium: `feature-workflow`,\n  `polishing-beads`, `implementing-beads` — tell the user which one is\n  missing. Do not cancel the Worker for it. Leave the Worker idle.\n- **A message that starts with `BM-BUDGET`** comes from the plugin, not the\n  user: the request has used more review calls than its tier allows (Small 1,\n  Medium 4, Large 6). Show the user the numbers, **ask the user whether to\n  continue or to cancel** the Worker's run, and wait. Never cancel on the notice\n  alone: the user may already have allowed the extra calls in the Worker's\n  chat. If they say continue, tell them so and send the Worker nothing. If they say\n  cancel, cancel the run and say what is unfinished.\n- **A Paseo notice that the Worker ended a turn WITHOUT a new `BM-REPORT`** is\n  not news: if the Worker errored or waits for a permission, tell the user;\n  otherwise reply with ONE status line.\n- **The Worker is stuck or off course:** cancel its run, tell the user why, and\n  wait.\n- **The user asks to stop a Worker:** cancel its run, confirm, and note that the\n  Worker must also stop its Reviewers and leave a final report.\n- **The user asks to archive or delete an agent:** explain it is the user's own\n  action in Paseo, and do not do it.\n\nHow you talk: keep replies to the user to a few lines, in the user's language —\nexcept the questions of a report with no buttons, which you show in full. Talk\nabout the request only: tool, connector and system notices that are not about it\nnever reach the user. Mention a real risk in one sentence at most.";

package/server/manager.ts

@@ -0,0 +1,647 @@
+/**
+ * `manager.ensure` on the daemon side (WP-112, design §5, §8, §9.3).
+ *
+ * One Manager per workspace: look the live Manager up by its `bm.role=manager`
+ * label BEFORE creating anything; when there is none, create one from the
+ * `bm-manager` agent profile with the instructions in `roles/manager.md` and the
+ * labels `bm.role=manager` + `bm.version=<plugin version>`. A Manager another
+ * Manager replaced does not count (delta 20260921 §4.5.2), and `createManager`
+ * is the one code path that creates a Manager, for `manager.ensure` and for a
+ * replacement alike.
+ *
+ * Lifecycle belongs to the user (ADR-005): this module never deletes or archives
+ * a healthy agent. The single exception is cleanup of the exact agent this call
+ * just created when the SDK handed it back already failed, so a failed ensure
+ * leaves no half-started Manager behind.
+ *
+ * SDK facts this relies on (checked against @getpaseo/client 0.8.0 typings and
+ * @getpaseo/protocol 0.8.0 schemas, not guessed):
+ * - `agents.list({ filter: { labels, includeArchived }, page: { limit<=200, cursor } })`;
+ *   the directory filter has NO workspace key, so the workspace is matched on
+ *   `entry.agent.workspaceId` here.
+ * - `agents.create` takes no profile id: `config.provider` is `provider/model`.
+ *   The profile is read from `config.get().config.agentProfiles[]`.
+ * - Agent snapshots carry `createdAt`, `status` (initializing|idle|running|error|closed),
+ *   `archivedAt` and `providerUnavailable`.
+ * - The only removal a handle offers is `archive()`; the SDK has no delete.
+ */
+import type { AgentNode } from "../shared/contracts";
+import { PLUGIN_VERSION } from "../shared/version";
+import { setAgentLabel, setAgentMode, type PaseoCliDeps } from "./paseo-cli";
+import { listAllAgents, roleOfAgent } from "./agent-role";
+import { providerId } from "./provider-id";
+import { AUTO_APPROVE_FEATURE, TIMED_OUT, capabilityOf, featuresFor, managerModeFor, modesFor, runPostureOf, withTimeout } from "./role-mode";
+import { workspaceDirectory, type DashboardPaseo } from "./dashboard-rpc";
+import { readIncidents } from "./fallback-state";
+import { installHomeOf } from "./role-extras";
+import { recordTools } from "./tools-check";
+
+/** Label key and value that identify a paseo-bm Manager (design §5). */
+export const MANAGER_ROLE_LABEL = "bm.role";
+export const MANAGER_ROLE_VALUE = "manager";
+export const VERSION_LABEL = "bm.version";
+
+/**
+ * "paseo-bm already set this Manager's mode", with the mode as its value
+ * (delta 20260918 §4.1). A Manager that carries it is never switched again, so
+ * a mode the user picks by hand afterwards is respected (owner decision Q36).
+ */
+export const MODE_SET_LABEL = "bm.modeSet";
+
+/** Label on an agent another agent replaced, with the replacement's id (delta 20260921 §4.4.8, §4.5.2). */
+const REPLACED_BY_LABEL = "bm.replacedBy";
+
+/** Agent profile id registered by the installer (ADR-006, WP-107). */
+export const MANAGER_PROFILE_ID = "bm-manager";
+
+/** Title given to a freshly created Manager. */
+export const MANAGER_TITLE = "Beads Manager";
+
+/**
+ * Error codes this RPC can report. Taken from the single Phase 1 registry in
+ * design §4.4 ("Không được đặt mã tại chỗ"); §5 itself lists no RPC codes.
+ */
+export type ManagerEnsureErrorCode = "E_PROVIDER_UNAVAILABLE";
+
+/**
+ * Coded failure of `manager.ensure`. The message starts with the code so it
+ * survives transports that only forward `message`.
+ */
+export class ManagerEnsureError extends Error {
+  readonly code: ManagerEnsureErrorCode;
+
+  constructor(code: ManagerEnsureErrorCode, detail: string, options?: { cause?: unknown }) {
+    super(`${code}: ${detail}`, options);
+    this.name = "ManagerEnsureError";
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Minimal, injectable view of the Paseo SDK. `PaseoApi` from @getpaseo/client
+// is structurally assignable to it (index.server.ts passes the real one, which
+// `npm run typecheck:plugin` checks); tests pass a fake.
+// ---------------------------------------------------------------------------
+
+export interface ManagerAgentSnapshot {
+  id: string;
+  workspaceId?: string;
+  createdAt: string;
+  status: string;
+  labels: Record<string, string>;
+  /** Provider selection (`bm-manager` or `bm-manager/<model>`); decides the role when the label is missing. */
+  provider?: string;
+  archivedAt?: string | null;
+  providerUnavailable?: boolean;
+  lastError?: string;
+  /** The mode the agent is in now; `agents.list` entries carry it. */
+  currentModeId?: string | null;
+  /** The agent's feature values, when the snapshot carries them (`auto_accept` on OpenCode). */
+  features?: ReadonlyArray<{ id?: string; value?: unknown }>;
+  /** What the agent's provider supports; `supportsMcpServers: false` means no Paseo tools (delta 20260921 §4.2.4). */
+  capabilities?: { supportsMcpServers?: unknown } | null;
+}
+
+export interface ManagerAgentHandle {
+  readonly id: string;
+  current(): ManagerAgentSnapshot | null;
+  archive(): Promise<unknown>;
+}
+
+export interface ManagerAgentProfile {
+  id: string;
+  provider: string;
+  model?: string;
+  modeId?: string;
+  thinkingOptionId?: string;
+  featureValues?: Record<string, unknown>;
+}
+
+export interface ManagerPaseo {
+  agents: {
+    list(options: {
+      filter: { labels?: Record<string, string>; includeArchived: boolean };
+      page: { limit: number; cursor?: string };
+    }): Promise<{
+      entries: Array<{ agent: ManagerAgentSnapshot }>;
+      pageInfo: { nextCursor: string | null; hasMore: boolean };
+    }>;
+  };
+  workspaces: {
+    ref(workspaceId: string): {
+      agents: {
+        create(options: {
+          config: {
+            provider: string;
+            modeId?: string;
+            thinkingOptionId?: string;
+            featureValues?: Record<string, unknown>;
+            systemPrompt?: string;
+          };
+          title?: string;
+          labels?: Record<string, string>;
+          /** The agent's first message (a replacement Manager's `BM-HANDOVER`, delta 20260921 §4.5.2). */
+          prompt?: string;
+        }): Promise<ManagerAgentHandle>;
+      };
+    };
+  };
+  config: {
+    get(): Promise<{ config: { agentProfiles?: ManagerAgentProfile[] } }>;
+  };
+  /** Absent on a host that cannot list modes; the Manager then gets no mode of ours. */
+  providers?: {
+    listModes(provider: string, options?: { cwd?: string }): Promise<unknown>;
+  };
+}
+
+export interface EnsureManagerDeps {
+  paseo: ManagerPaseo;
+  /** Returns the text of `roles/manager.md`. */
+  readInstructions: () => Promise<string>;
+  /** Plugin version written to `bm.version`. Defaults to the baked-in version. */
+  version?: string;
+  /** Where a failed mode lookup is reported. Defaults to `console.warn`. */
+  log?: (message: string) => void;
+  /** How the `paseo` CLI is found and run; tests pass a fake runner. */
+  cli?: PaseoCliDeps;
+  /**
+   * The workspace's directory, needed to read an untiered provider's features
+   * (delta 20260921 §4.2.2). Defaults to the directory Paseo lists for it.
+   */
+  workspaceDirectory?: (workspaceId: string) => Promise<string | null>;
+  /**
+   * The install home, whose `role-fallback-state.json` names the replaced
+   * Managers (delta 20260921 §4.5.2); `null` means none. Looked up within the
+   * lookup budget when absent; tests pass one.
+   */
+  home?: string | null;
+}
+
+export interface EnsureManagerResult {
+  agentId: string;
+  created: boolean;
+  /**
+   * Other live Managers found in the same workspace, newest first, never a
+   * replaced one. Reported so the panel can tell the user (design §9.3); never
+   * deleted or archived here.
+   */
+  otherManagerIds: string[];
+  /**
+   * Why an existing Manager was not switched to its mode, or `null` when there
+   * was nothing to say (delta 20260918 §4.1). Never blocks returning the Manager.
+   */
+  modeNotice: string | null;
+  /**
+   * Set when the Manager just created has no Paseo tools (Pi without
+   * pi-mcp-adapter), so it cannot create or message a Worker (delta 20260921
+   * §4.2.4); `null` otherwise, and always for an existing Manager.
+   */
+  toolsNotice: string | null;
+}
+
+/** A Manager is live when it is neither archived nor closed. */
+function isLive(agent: ManagerAgentSnapshot): boolean {
+  return !agent.archivedAt && agent.status !== "closed";
+}
+
+/** Newest first by `createdAt`; ties broken by id so the choice is stable. */
+function newestFirst(a: ManagerAgentSnapshot, b: ManagerAgentSnapshot): number {
+  const byTime = Date.parse(b.createdAt) - Date.parse(a.createdAt);
+  if (byTime !== 0 && !Number.isNaN(byTime)) return byTime;
+  return a.id < b.id ? 1 : a.id > b.id ? -1 : 0;
+}
+
+/** True when the Manager carries the `bm.role=manager` label; false when only its provider says so. */
+function labelledManager(agent: ManagerAgentSnapshot): boolean {
+  return roleOfAgent(agent)?.labelled === true;
+}
+
+/**
+ * Every live Manager of the workspace: labelled Managers first, then the ones
+ * recognised only by their `bm-manager` provider (started from Paseo's own
+ * new-agent flow), each group newest first (delta 20260918g §4.3). Listing
+ * with no label filter is what lets the second group be found at all; without
+ * it `manager.ensure` created a second Manager next to the user's own.
+ *
+ * A replaced Manager is left out (delta 20260921 §4.5.2): it carries
+ * `bm.replacedBy`, or — when labelling it failed — it is the `agentId` of a
+ * `switched` Manager incident. So `manager.ensure` opens the replacement and
+ * never reports the old one, which stays alive until the user archives it
+ * (ADR-005). The incidents are only read when a live Manager is found.
+ */
+export async function findLiveManagers(
+  paseo: ManagerPaseo,
+  workspaceId: string,
+  lookup: { home?: string | null; log?: (message: string) => void } = {},
+): Promise<ManagerAgentSnapshot[]> {
+  const all = await listAllAgents((options) => paseo.agents.list(options), { includeArchived: false });
+  const live = all.filter(
+    (agent) =>
+      agent.workspaceId === workspaceId &&
+      roleOfAgent(agent)?.role === "manager" &&
+      isLive(agent) &&
+      agent.labels?.[REPLACED_BY_LABEL] === undefined,
+  );
+  const replaced = live.length === 0 ? new Set<string>() : await replacedManagerIds(paseo, lookup);
+  return live
+    .filter((agent) => !replaced.has(agent.id))
+    .sort((a, b) => Number(labelledManager(b)) - Number(labelledManager(a)) || newestFirst(a, b));
+}
+
+/**
+ * The `agentId` of every `switched` Manager incident in the install home's
+ * `role-fallback-state.json` (delta 20260921 §4.5.2). Empty when the home is
+ * not found within the lookup budget or the file cannot be used; the
+ * `bm.replacedBy` label still applies then. Never throws.
+ */
+async function replacedManagerIds(
+  paseo: ManagerPaseo,
+  lookup: { home?: string | null; log?: (message: string) => void },
+): Promise<Set<string>> {
+  try {
+    const home = lookup.home !== undefined ? lookup.home : await withTimeout(installHomeOf(paseo));
+    if (home === null || home === TIMED_OUT) return new Set();
+    return new Set(
+      readIncidents(home, lookup.log)
+        .incidents.filter((incident) => incident.role === "manager" && incident.status === "switched")
+        .map((incident) => incident.agentId),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+/** The workspace's directory for a features lookup, or `null`. Never throws. */
+async function directoryOf(deps: EnsureManagerDeps, workspaceId: string): Promise<string | null> {
+  try {
+    return deps.workspaceDirectory !== undefined
+      ? await deps.workspaceDirectory(workspaceId)
+      : await workspaceDirectory(deps.paseo as unknown as DashboardPaseo, workspaceId);
+  } catch {
+    return null;
+  }
+}
+
+function providerSelection(profile: ManagerAgentProfile): string {
+  return profile.model ? `${profile.provider}/${profile.model}` : profile.provider;
+}
+
+/** The snapshot of a just-created agent says its provider could not start. */
+function startedBroken(snapshot: ManagerAgentSnapshot | null): boolean {
+  return snapshot !== null && (snapshot.status === "error" || snapshot.providerUnavailable === true);
+}
+
+/**
+ * Handler body of `manager.ensure`.
+ *
+ * Throws `ManagerEnsureError` (`E_PROVIDER_UNAVAILABLE`) when the Manager cannot
+ * be created: the `bm-manager` profile is missing, the SDK rejects the create,
+ * or the created agent comes back already failed (then that exact agent is
+ * archived before throwing).
+ */
+export async function ensureManager(
+  input: { workspaceId: string },
+  deps: EnsureManagerDeps,
+): Promise<EnsureManagerResult> {
+  const { paseo } = deps;
+  const { workspaceId } = input;
+
+  const [chosen, ...others] = await findLiveManagers(paseo, workspaceId, { home: deps.home, log: deps.log });
+  if (chosen) {
+    return {
+      agentId: chosen.id,
+      created: false,
+      otherManagerIds: others.map((agent) => agent.id),
+      // A Manager recognised only by its provider was created by the user in a
+      // mode they chose: paseo-bm never switches it (delta 20260918g §4.3).
+      modeNotice: labelledManager(chosen) ? await switchOnce(chosen, deps) : null,
+      toolsNotice: null,
+    };
+  }
+
+  const { config } = await paseo.config.get();
+  const profile = config.agentProfiles?.find((entry) => entry.id === MANAGER_PROFILE_ID);
+  if (!profile) {
+    throw new ManagerEnsureError(
+      "E_PROVIDER_UNAVAILABLE",
+      `agent profile "${MANAGER_PROFILE_ID}" is not registered on this daemon; re-run \`npx paseo-bm\` to register the roles.`,
+    );
+  }
+
+  // The provider's no-prompt mode unless the profile names its own (delta
+  // 20260918 §4.1). `modesFor` is raced against 5 s and logs every miss; a miss
+  // creates the Manager exactly as before, without the label, so the next open
+  // can still switch it.
+  const provider = providerId(profile.provider) ?? profile.provider;
+  const modes = await modesFor(paseo, provider, deps.log);
+  const capability = capabilityOf(modes);
+  let chosenMode: string | undefined;
+  let modeId: string | undefined;
+  let featureValues = profile.featureValues;
+  if (capability === "untiered" || capability === "none") {
+    // Delta 20260921 §4.2.2: OpenCode (untiered) gets a listed mode — the
+    // profile's, else the first — and auto-approve on unless the profile sets
+    // it; Pi (none) gets neither.
+    const features =
+      capability === "untiered"
+        ? await featuresFor(paseo, providerSelection(profile), (await directoryOf(deps, workspaceId)) ?? undefined, deps.log)
+        : null;
+    const posture = runPostureOf("manager", capability, modes ?? [], features, profile.modeId ?? null, {
+      ...(profile.featureValues !== undefined ? { featureValues: profile.featureValues } : {}),
+    });
+    chosenMode = posture?.modeId ?? undefined;
+    modeId = chosenMode;
+    // `null` removes the key: a Manager on a provider without modes (Pi) gets no
+    // mode and no feature, even when its profile sets them (review b4).
+    if (posture?.featureValues === null) featureValues = undefined;
+    else if (posture?.featureValues !== undefined) featureValues = posture.featureValues;
+  } else {
+    chosenMode = modes === null ? undefined : managerModeFor(modes, profile.modeId ?? null);
+    // Modes unknown: exactly as before this delta. Modes known: only a mode the
+    // provider lists — a profile mode it does not list would make the creation fail.
+    modeId = modes === null ? profile.modeId : chosenMode;
+  }
+  if (capability === "tiered" && chosenMode === undefined) {
+    (deps.log ?? ((message: string) => console.warn(message)))(
+      `[paseo-bm] ${provider} lists no mode that runs without permission prompts${
+        profile.modeId === undefined ? "" : `, nor the profile's own mode "${profile.modeId}"`
+      }; the Manager starts in the provider's default mode.`,
+    );
+  }
+
+  const created = await createManager(paseo, workspaceId, {
+    providerSelection: providerSelection(profile),
+    modeId,
+    thinkingOptionId: profile.thinkingOptionId,
+    featureValues,
+    labels: chosenMode !== undefined ? { [MODE_SET_LABEL]: chosenMode } : {},
+    readInstructions: deps.readInstructions,
+    version: deps.version,
+  });
+  return { agentId: created.agentId, created: true, otherManagerIds: [], modeNotice: null, toolsNotice: created.toolsNotice };
+}
+
+/** What `createManager` creates; the caller has already decided the provider, mode and thinking. */
+export interface CreateManagerOptions extends Pick<EnsureManagerDeps, "readInstructions" | "version"> {
+  /** `provider/model`: `bm-manager/<model>` from the profile, or `bm-manager-fallback-<n>/<model>` for a replacement. */
+  providerSelection: string;
+  modeId?: string;
+  thinkingOptionId?: string;
+  featureValues?: Record<string, unknown>;
+  /**
+   * Added to `bm.role=manager` and `bm.version`: `bm.modeSet` when paseo-bm
+   * chose the mode (not for a profile mode passed on unchecked), `bm.replaces`
+   * for a replacement (delta 20260921 §4.5.2).
+   */
+  labels: Record<string, string>;
+  /** The Manager's first message: a replacement's `BM-HANDOVER`. None when absent. */
+  prompt?: string;
+}
+
+export interface CreateManagerResult {
+  agentId: string;
+  /** As `EnsureManagerResult.toolsNotice`. */
+  toolsNotice: string | null;
+}
+
+/**
+ * Creates a Manager in the workspace: the one code path for `manager.ensure`
+ * and for a replacement Manager (delta 20260921 §4.5.2), so both get the same
+ * instructions and Runtime facts (`readInstructions`), the same labels and the
+ * same `toolsNotice`.
+ *
+ * Throws `ManagerEnsureError` (`E_PROVIDER_UNAVAILABLE`) when the SDK rejects
+ * the create, or when the created agent comes back already failed (then that
+ * exact agent is archived before throwing).
+ */
+export async function createManager(
+  paseo: ManagerPaseo,
+  workspaceId: string,
+  options: CreateManagerOptions,
+): Promise<CreateManagerResult> {
+  const { providerSelection: selection, modeId, thinkingOptionId, featureValues, prompt } = options;
+  const systemPrompt = await options.readInstructions();
+  // `manager.ensure` names the profile, as it always has; a replacement names its provider.
+  const alias = providerId(selection) ?? selection;
+  const source = alias === MANAGER_PROFILE_ID ? `profile "${MANAGER_PROFILE_ID}"` : `provider "${selection}"`;
+
+  let handle: ManagerAgentHandle;
+  try {
+    handle = await paseo.workspaces.ref(workspaceId).agents.create({
+      config: {
+        provider: selection,
+        ...(modeId !== undefined ? { modeId } : {}),
+        ...(thinkingOptionId !== undefined ? { thinkingOptionId } : {}),
+        ...(featureValues !== undefined ? { featureValues } : {}),
+        systemPrompt,
+      },
+      title: MANAGER_TITLE,
+      labels: {
+        [MANAGER_ROLE_LABEL]: MANAGER_ROLE_VALUE,
+        [VERSION_LABEL]: options.version ?? PLUGIN_VERSION,
+        ...options.labels,
+      },
+      ...(prompt !== undefined ? { prompt } : {}),
+    });
+  } catch (cause) {
+    throw new ManagerEnsureError(
+      "E_PROVIDER_UNAVAILABLE",
+      `could not create the Manager with ${source}: ${cause instanceof Error ? cause.message : String(cause)}`,
+      { cause },
+    );
+  }
+
+  const snapshot = handle.current();
+  if (startedBroken(snapshot)) {
+    // Clean up exactly the agent this call created; nothing else is touched.
+    let cleanup = "it was archived";
+    try {
+      await handle.archive();
+    } catch (archiveError) {
+      cleanup = `archiving it failed (${archiveError instanceof Error ? archiveError.message : String(archiveError)}); archive agent ${handle.id} yourself`;
+    }
+    throw new ManagerEnsureError(
+      "E_PROVIDER_UNAVAILABLE",
+      `the Manager's provider did not start${snapshot?.lastError ? `: ${snapshot.lastError}` : ""}; ${cleanup}.`,
+    );
+  }
+
+  // Delta 20260921 §4.2.4: a Manager without Paseo tools cannot run a request.
+  const supports = snapshot?.capabilities?.supportsMcpServers;
+  recordTools("manager", handle.id, selection, supports);
+  const toolsNotice =
+    supports === false
+      ? `This Manager runs on ${selection} without Paseo tools (on Pi this means pi-mcp-adapter is missing): it cannot create or message a Worker.`
+      : null;
+  return { agentId: handle.id, toolsNotice };
+}
+
+/**
+ * Switches a Manager created before delta 20260918 to its mode, once, and marks
+ * it with `bm.modeSet` (§4.1, owner decisions Q36, Q37, Q39). Returns what the
+ * user should be told, or `null`. Never throws: whatever goes wrong, the
+ * Manager is still opened.
+ */
+async function switchOnce(manager: ManagerAgentSnapshot, deps: EnsureManagerDeps): Promise<string | null> {
+  try {
+    // 1. Already handled: a mode the user picked since then is theirs.
+    if (manager.labels[MODE_SET_LABEL] !== undefined) return null;
+
+    // 2. The same target a new Manager would get; no target, nothing to do.
+    const { config } = await deps.paseo.config.get();
+    const profile = config.agentProfiles?.find((entry) => entry.id === MANAGER_PROFILE_ID);
+    if (!profile) return null;
+    const provider = providerId(profile.provider) ?? profile.provider;
+    const modes = await modesFor(deps.paseo, provider, deps.log);
+    if (capabilityOf(modes) === "untiered") {
+      // The plugin cannot change the features of an existing agent (proposal
+      // S9), so auto-approve cannot be turned on here (delta 20260921 §4.2.2).
+      const autoApprove = manager.features?.find((feature) => feature?.id === AUTO_APPROVE_FEATURE)?.value === true;
+      return autoApprove
+        ? null
+        : `This Manager runs on ${provider} and was created before paseo-bm could turn on auto-approve for it; it may ask for permissions. Start a new Manager to run without prompts.`;
+    }
+    const target = modes === null ? undefined : managerModeFor(modes, profile.modeId ?? null);
+    if (target === undefined) return null;
+
+    // 3. Switching mid-turn can rebuild a Claude session's query: wait for the next open.
+    if (manager.status === "running") {
+      return `Beads Manager ${manager.id} is busy, so it was not switched to "${target}" yet; paseo-bm will try again the next time you open it.`;
+    }
+
+    // 4. Switch only when it is not already there.
+    if (manager.currentModeId !== target) {
+      const switched = await setAgentMode(manager.id, target, deps.cli);
+      if (!switched.ok) {
+        return `Could not switch Beads Manager ${manager.id} to "${target}": ${switched.reason}. Switch its mode yourself in Paseo.`;
+      }
+    }
+
+    // 5. Mark it, so it is never switched again. A miss here only means the next open marks it.
+    const marked = await setAgentLabel(manager.id, MODE_SET_LABEL, target, deps.cli);
+    if (!marked.ok) {
+      return `Beads Manager ${manager.id} is in "${target}", but could not be marked as done (${marked.reason}); paseo-bm will try again the next time you open it.`;
+    }
+    return null;
+  } catch (error) {
+    return `Could not check the mode of Beads Manager ${manager.id}: ${error instanceof Error ? error.message : String(error)}. Switch its mode yourself in Paseo if it still asks for permission.`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// `agents.list` (WP-112, design §5, REQ-025a)
+// ---------------------------------------------------------------------------
+
+/** Label Paseo sets on an agent created by another agent (AGENTS.md, verified). */
+export const PARENT_AGENT_LABEL = "paseo.parent-agent-id";
+
+/** Snapshot fields `agents.list` reads. `PaseoAgent` is structurally assignable. */
+export interface ListedAgentSnapshot {
+  id: string;
+  workspaceId?: string;
+  title: string | null;
+  status: string;
+  createdAt: string;
+  updatedAt: string;
+  labels: Record<string, string>;
+  /** Provider selection; decides the role when the `bm.role` label is missing. */
+  provider?: string;
+  archivedAt?: string | null;
+}
+
+/**
+ * Minimal SDK view for `agents.list`. The directory filter's `labels` is
+ * optional in the protocol, and it must be omitted here: an unlabeled agent can
+ * only be recognised through its parent.
+ */
+export interface AgentDirectoryPaseo {
+  agents: {
+    list(options: {
+      filter: { includeArchived: boolean };
+      page: { limit: number; cursor?: string };
+    }): Promise<{
+      entries: Array<{ agent: ListedAgentSnapshot }>;
+      pageInfo: { nextCursor: string | null; hasMore: boolean };
+    }>;
+  };
+}
+
+/** The label's role, else the provider's (delta 20260918g §4.1), else `unknown`. */
+function roleOf(agent: ListedAgentSnapshot): AgentNode["role"] {
+  return roleOfAgent(agent)?.role ?? "unknown";
+}
+
+/** Oldest first by `createdAt`, ties by id, so the list order is stable. */
+function oldestFirst(a: ListedAgentSnapshot, b: ListedAgentSnapshot): number {
+  const byTime = Date.parse(a.createdAt) - Date.parse(b.createdAt);
+  if (byTime !== 0 && !Number.isNaN(byTime)) return byTime;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+/**
+ * Handler body of `agents.list`: the non-archived paseo-bm agents of one
+ * workspace, flat, oldest first.
+ *
+ * Membership: an agent with a paseo-bm role — by its `bm.role` label or, when
+ * that is missing, by its `bm-*` provider (delta 20260918g) — plus every agent
+ * that descends from one through `paseo.parent-agent-id` (an agent of another
+ * provider under a Worker still shows up, with role `unknown`). A node without a
+ * valid label is `labelled: false`; nothing here throws on labels.
+ *
+ * `parentId` is the parent label only when that parent is in the result. A
+ * parent that was deleted or archived yields `null`, so an orphaned Worker is a
+ * root the client can still draw. Read-only: nothing is stopped or archived.
+ */
+export async function listWorkspaceAgents(
+  input: { workspaceId: string },
+  deps: {
+    paseo: AgentDirectoryPaseo;
+    /** Agent id → its replacement, from `switched` fallback incidents (delta 20260921 §4.4.8). */
+    replacements?: ReadonlyMap<string, string>;
+  },
+): Promise<{ agents: AgentNode[] }> {
+  const all = await listAllAgents((options) => deps.paseo.agents.list(options), {
+    includeArchived: false,
+  });
+  const inWorkspace = all.filter(
+    (agent) => agent.workspaceId === input.workspaceId && !agent.archivedAt,
+  );
+
+  // Roots: every agent with a paseo-bm role, by label or by provider, and — as
+  // before delta 20260918g — any agent carrying a `bm.role` label at all.
+  const members = new Set(
+    inWorkspace
+      .filter((agent) => roleOfAgent(agent) !== null || agent.labels[MANAGER_ROLE_LABEL] !== undefined)
+      .map((a) => a.id),
+  );
+  // Pull in descendants until the set stops growing (depth is small; bounded by n passes).
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const agent of inWorkspace) {
+      const parent = agent.labels[PARENT_AGENT_LABEL];
+      if (!members.has(agent.id) && parent !== undefined && members.has(parent)) {
+        members.add(agent.id);
+        grew = true;
+      }
+    }
+  }
+
+  const agents = inWorkspace
+    .filter((agent) => members.has(agent.id))
+    .sort(oldestFirst)
+    .map((agent): AgentNode => {
+      const parent = agent.labels[PARENT_AGENT_LABEL];
+      return {
+        id: agent.id,
+        role: roleOf(agent),
+        title: agent.title,
+        status: agent.status,
+        parentId: parent !== undefined && members.has(parent) ? parent : null,
+        updatedAt: agent.updatedAt,
+        labelled: roleOfAgent(agent)?.labelled ?? false,
+        replacedBy: agent.labels["bm.replacedBy"] ?? deps.replacements?.get(agent.id) ?? null,
+      };
+    });
+  return { agents };
+}