paseo-bm-plugin 0.0.0-placeholder.0

package/server/paseo-cli.ts

@@ -0,0 +1,115 @@
+/**
+ * The two `paseo` CLI commands the plugin runs (delta 20260918 §4.1).
+ *
+ * The plugin SDK cannot change an existing agent's mode or labels:
+ * `PaseoAgentHandle` has no setter for either, `DaemonClient.setAgentMode` is
+ * not handed to plugins, and `before("agent.session_open")` only edits `env`
+ * (N2, N3). Paseo CLI 0.8 can: `paseo agent mode <id> <mode>` and
+ * `paseo agent update <id> --label <k=v>`. The binary is found the way the
+ * Setup screen finds `br` (`findTool`), and run the way it runs one: `execFile`,
+ * never a shell, with a timeout.
+ *
+ * Every argument is checked before it reaches the command line. A value that
+ * starts with `-` would be read as a flag, so ids, modes and labels must start
+ * with a letter or digit and hold nothing but the characters Paseo uses.
+ */
+import { execFile } from "node:child_process";
+import { findTool } from "./setup-tools";
+
+/** How long one CLI call may take before it counts as failed. */
+export const CLI_TIMEOUT_MS = 5000;
+
+/** An agent id as Paseo mints it: never a flag, never a path. */
+const AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** A mode id, a label key or a label value: never a flag, no `=` or spaces. */
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export interface CliOutcome {
+  code: number;
+  output: string;
+  timedOut: boolean;
+}
+
+export type CliRunner = (file: string, args: string[], timeoutMs: number) => Promise<CliOutcome>;
+
+export interface PaseoCliDeps {
+  /** Runs the binary. Tests pass a fake; nothing in a test may start the real `paseo`. */
+  run?: CliRunner;
+  /** Finds the `paseo` binary, or `null`. */
+  find?: () => string | null;
+}
+
+export type CliResult = { ok: true } | { ok: false; reason: string };
+
+export function isSafeAgentId(id: string): boolean {
+  return AGENT_ID.test(id);
+}
+
+function runExecFile(file: string, args: string[], timeoutMs: number): Promise<CliOutcome> {
+  return new Promise((resolve) => {
+    execFile(file, args, { timeout: timeoutMs, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+      const failure = error as (Error & { code?: unknown; killed?: boolean }) | null;
+      const code = failure === null ? 0 : typeof failure.code === "number" ? failure.code : 1;
+      resolve({ code, output: `${stdout}${stderr}`, timedOut: failure?.killed === true });
+    });
+  });
+}
+
+/** The first non-empty line of the CLI's output, short enough for a notice. */
+function firstLine(output: string): string {
+  const line = output.split("\n").map((part) => part.trim()).find((part) => part !== "") ?? "";
+  return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}
+
+async function runPaseo(args: string[], deps: PaseoCliDeps): Promise<CliResult> {
+  const binary = (deps.find ?? (() => findTool("paseo")))();
+  if (binary === null) return { ok: false, reason: "the `paseo` command was not found" };
+  let outcome: CliOutcome;
+  try {
+    outcome = await (deps.run ?? runExecFile)(binary, args, CLI_TIMEOUT_MS);
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (outcome.timedOut) return { ok: false, reason: `\`paseo ${args.slice(0, 2).join(" ")}\` took longer than ${CLI_TIMEOUT_MS} ms` };
+  if (outcome.code !== 0) {
+    const detail = firstLine(outcome.output);
+    return { ok: false, reason: `\`paseo ${args.slice(0, 2).join(" ")}\` exited with ${outcome.code}${detail === "" ? "" : `: ${detail}`}` };
+  }
+  return { ok: true };
+}
+
+/** `paseo agent mode <id> <mode> --json`. */
+export function setAgentMode(agentId: string, modeId: string, deps: PaseoCliDeps = {}): Promise<CliResult> {
+  if (!isSafeAgentId(agentId)) return Promise.resolve({ ok: false, reason: `refusing an unexpected agent id "${agentId}"` });
+  if (!TOKEN.test(modeId)) return Promise.resolve({ ok: false, reason: `refusing an unexpected mode "${modeId}"` });
+  return runPaseo(["agent", "mode", agentId, modeId, "--json"], deps);
+}
+
+/** `paseo agent update <id> --label <key>=<value> --json`. */
+export function setAgentLabel(agentId: string, key: string, value: string, deps: PaseoCliDeps = {}): Promise<CliResult> {
+  if (!isSafeAgentId(agentId)) return Promise.resolve({ ok: false, reason: `refusing an unexpected agent id "${agentId}"` });
+  if (!TOKEN.test(key) || !TOKEN.test(value)) {
+    return Promise.resolve({ ok: false, reason: `refusing an unexpected label "${key}=${value}"` });
+  }
+  return runPaseo(["agent", "update", agentId, "--label", `${key}=${value}`, "--json"], deps);
+}
+
+/**
+ * `paseo agent update <id> --label <k>=<v> [--label <k>=<v> …] --json`: one
+ * command for several labels. Paseo adds or sets each label and removes none
+ * (`paseo agent update --help`, 0.8.0). Every key and value is checked first.
+ */
+export function setAgentLabels(agentId: string, labels: Readonly<Record<string, string>>, deps: PaseoCliDeps = {}): Promise<CliResult> {
+  if (!isSafeAgentId(agentId)) return Promise.resolve({ ok: false, reason: `refusing an unexpected agent id "${agentId}"` });
+  const entries = Object.entries(labels);
+  if (entries.length === 0) return Promise.resolve({ ok: false, reason: "no label to set" });
+  const args = ["agent", "update", agentId];
+  for (const [key, value] of entries) {
+    if (!TOKEN.test(key) || !TOKEN.test(value)) {
+      return Promise.resolve({ ok: false, reason: `refusing an unexpected label "${key}=${value}"` });
+    }
+    args.push("--label", `${key}=${value}`);
+  }
+  args.push("--json");
+  return runPaseo(args, deps);
+}

package/server/provider-id.ts

@@ -0,0 +1,12 @@
+/**
+ * Provider id of a provider selection: `bm-worker` and `bm-worker/<model>` both
+ * name the `bm-worker` provider. Anything that is not a string yields `null`.
+ *
+ * Shared by the `agent.create` role hook and the `agent.turn_ended` stop
+ * propagation so both recognise paseo-bm roles the same way.
+ */
+export function providerId(provider: unknown): string | null {
+  if (typeof provider !== "string") return null;
+  const slash = provider.indexOf("/");
+  return slash === -1 ? provider : provider.slice(0, slash);
+}

package/server/review-budget.ts

@@ -0,0 +1,208 @@
+/**
+ * Review budget, counted by the plugin (delta 20260917c §4.7, REQ-037 errata).
+ *
+ * The Worker used to count its own review calls and the Manager used to check
+ * the count. The 2026-09-17 acceptance run showed the trace store counting 4
+ * calls correctly while the Worker reported 5, so the number now comes from the
+ * one place that gets it right: `reviewCallsOf`, the same figure the Dashboard
+ * shows. The guardrail stays behavioural — this module only TELLS the Manager;
+ * the Manager decides and the user permits. Nothing here stops an agent.
+ *
+ * Two properties this module must never lose (review b2):
+ * - It only ever tells the Manager about an overrun a Worker's or Reviewer's
+ *   turn end DISCOVERED in this process. A Manager turn end can only flush
+ *   what is already pending. Without that, a restart would make the first
+ *   Manager turn end announce every old finished request, and each notice
+ *   starts a Manager turn whose end announces the next one.
+ * - One notice per request, even when two turn ends are handled at once: the
+ *   request is marked before the first `await`, not after the send.
+ *
+ * Facts this relies on (checked, not guessed):
+ * - A Reviewer's inbound request is recorded when that Reviewer's turn ends, so
+ *   a new call becomes visible at a Reviewer turn end. The Worker's last report
+ *   usually WAKES the Manager, so a notice found at the Worker's turn end is
+ *   deferred — which is why the MANAGER's own turn end is checked too, and is
+ *   often the moment the notice can finally go out (review b1, B2).
+ * - `PaseoAgentHandle.send()` on a running agent REPLACES its current turn —
+ *   `stop-propagation.ts` relies on exactly that to interrupt a Reviewer. A
+ *   Manager in the middle of answering the user must not be cut off, so the
+ *   notice is sent only when `refresh()` says the Manager is not `running`.
+ * - A Manager turn is attributed to the request whose `requestId: req-…` it
+ *   contains (`managerRequestId`), so the notice carries that exact form and
+ *   never opens a request of its own.
+ *
+ * Lifecycle belongs to the user (ADR-005): nothing here archives, deletes or
+ * cancels anything.
+ */
+import type { PluginLifecycleEvents } from "@getpaseo/plugin/server";
+import type { Tier } from "../shared/contracts";
+import { agentFactsOf, reviewerReplacementsFor, type DashboardPaseo } from "./dashboard-rpc";
+import { BUDGET_NOTICE_MARKER } from "./notices";
+import { roleOfProvider } from "./agent-role";
+import { readRecords, type TraceStoreLocation } from "./trace-store";
+import { reconstructTraces, type ReconstructedTrace } from "./traces";
+
+/** Total review calls per request, by tier (REQ-037; unchanged by this delta). */
+export const REVIEW_BUDGET: Readonly<Record<Tier, number>> = { Small: 1, Medium: 4, Large: 6 };
+
+/** First word of the notice; `roles/manager.md` tells the Manager what to do with it. */
+export { BUDGET_NOTICE_MARKER } from "./notices";
+
+/**
+ * The fixed notice the Manager receives, word for word from design delta §4.7.
+ * The Manager ASKS the user; it never cancels on the notice alone, because the
+ * user may have allowed the extra calls in the Worker's own chat (REQ-026e,
+ * owner decision Q21). `roles/manager.md` pins the same text.
+ */
+export function budgetNotice(over: BudgetOverrun): string {
+  return (
+    `${BUDGET_NOTICE_MARKER} requestId: ${over.requestId}\n` +
+    `The Worker has used ${over.calls} review calls; the ${over.tier} budget is ${over.budget}. ` +
+    "Ask the user whether to continue or to cancel the Worker's run, and wait for the answer. " +
+    "Do not cancel on your own: the user may already have allowed the extra calls in the Worker's chat."
+  );
+}
+
+export interface BudgetOverrun {
+  requestId: string;
+  tier: Tier;
+  calls: number;
+  budget: number;
+  managerAgentId: string;
+}
+
+/**
+ * The overrun of one reconstructed request, or `null` when it is within
+ * budget, or when its tier, its call count, its request id or its Manager is
+ * not known — an unknown number never produces a notice.
+ */
+export function overrunOf(trace: ReconstructedTrace): BudgetOverrun | null {
+  if (trace.requestId === null || trace.tier === null || trace.reviewCalls === null) return null;
+  if (trace.managerAgentId === null) return null;
+  const budget = REVIEW_BUDGET[trace.tier];
+  if (budget === undefined || trace.reviewCalls <= budget) return null;
+  return {
+    requestId: trace.requestId,
+    tier: trace.tier,
+    calls: trace.reviewCalls,
+    budget,
+    managerAgentId: trace.managerAgentId,
+  };
+}
+
+type TurnEndedEvent = PluginLifecycleEvents["agent.turn_ended"];
+
+/** What the check needs from Paseo: the Dashboard's agent listing, plus refresh and send. */
+export interface BudgetPaseo extends Omit<DashboardPaseo, "agents"> {
+  agents: Omit<DashboardPaseo["agents"], "ref"> & {
+    ref?(agentId: string): {
+      timeline: { refetch(options: Record<string, unknown>): Promise<unknown> };
+      refresh?(): Promise<{ agent?: { status?: string | null; archivedAt?: string | null } | null } | null>;
+      send?(text: string): Promise<void>;
+    };
+  };
+}
+
+export interface BudgetDeps {
+  location: TraceStoreLocation;
+  paseo: BudgetPaseo;
+  /** `workspaceId::requestId` of every request already told, or being told now. */
+  told: Set<string>;
+  /**
+   * Overruns found at a Worker's or Reviewer's turn end that could not be sent
+   * yet (the Manager was running). Only these may go out at a Manager turn end,
+   * so a restart never announces old finished requests.
+   */
+  pending?: Map<string, BudgetOverrun>;
+  log?: (message: string) => void;
+  /**
+   * The install home, whose `role-fallback-state.json` names the Reviewers
+   * that replaced a stopped one (delta 20260921 §4.5.1); looked up otherwise.
+   */
+  home?: string | null;
+}
+
+export type BudgetOutcome = "ignored" | "within" | "already-told" | "deferred" | "sent";
+
+const NO_PENDING = new Map<string, BudgetOverrun>();
+
+/**
+ * Checks the requests of the agent whose turn just ended, and tells their
+ * Manager once each when a request is over budget. Call it only after the
+ * collector has written that turn's record. One notice per call, so a Manager
+ * is never sent two messages back to back; the next turn end carries the next.
+ * Never throws.
+ */
+export async function checkReviewBudget(event: TurnEndedEvent, deps: BudgetDeps): Promise<BudgetOutcome> {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  const pending = deps.pending ?? NO_PENDING;
+  let claimed: string | null = null;
+  try {
+    const agent = event?.agent;
+    // Every paseo-bm role counts, on its main alias or a fallback one (delta 20260921 §4.4.1).
+    const role = roleOfProvider(agent?.provider);
+    const workspaceId = agent?.workspaceId ?? null;
+    if (role === null || workspaceId === null) return "ignored";
+    const keyOf = (found: BudgetOverrun): string => `${workspaceId}::${found.requestId}`;
+
+    let over: BudgetOverrun | undefined;
+    if (role === "manager") {
+      // A Manager turn end only FLUSHES what a Worker or Reviewer turn end
+      // already found — usually the notice deferred moments ago because this
+      // Manager was still answering the Worker's last report.
+      over = [...pending.values()].find((found) => keyOf(found) === `${workspaceId}::${found.requestId}` && found.managerAgentId === agent.id);
+      if (over === undefined) return "within";
+    } else {
+      const records = readRecords(deps.location, workspaceId).records;
+      // A replacement Reviewer's first message is the stopped Reviewer's
+      // review call sent again, not a new one (delta 20260921 §4.5.1).
+      const [facts, replacementIds] = await Promise.all([
+        agentFactsOf(deps.paseo, workspaceId),
+        reviewerReplacementsFor(deps.paseo, { home: deps.home }),
+      ]);
+      const trace = reconstructTraces({ records, agents: [...facts.values()], replacementIds }).find(
+        (candidate) => candidate.workerIds.includes(agent.id) || candidate.reviewerIds.includes(agent.id),
+      );
+      over = trace === undefined ? undefined : (overrunOf(trace) ?? undefined);
+      if (over === undefined) return "within";
+      if (deps.told.has(keyOf(over))) return "already-told";
+      pending.set(keyOf(over), over);
+    }
+
+    const key = keyOf(over);
+    if (deps.told.has(key)) return "already-told";
+    // Claimed BEFORE any await: two turn ends handled at once must not both send.
+    deps.told.add(key);
+    claimed = key;
+
+    const handle = deps.paseo.agents.ref?.(over.managerAgentId);
+    if (typeof handle?.refresh !== "function" || typeof handle.send !== "function") {
+      log("[paseo-bm] cannot reach the Manager on this host; the review budget notice was not sent.");
+      return "deferred";
+    }
+    const snapshot = await handle.refresh();
+    const status = snapshot?.agent?.status ?? null;
+    if (status === "running") return "deferred";
+    // Lifecycle belongs to the user (ADR-005): `send()` un-archives an archived
+    // agent and starts a turn on it, so an archived or closed Manager is left
+    // alone and the notice is dropped rather than deferred forever.
+    if (snapshot?.agent?.archivedAt != null || status === "closed") {
+      log(`[paseo-bm] the Manager of ${over.requestId} is archived or closed; the review budget notice was not sent.`);
+      pending.delete(key);
+      claimed = null;
+      return "ignored";
+    }
+
+    await handle.send(budgetNotice(over));
+    pending.delete(key);
+    claimed = null;
+    return "sent";
+  } catch (error) {
+    // This runs inside a real agent's turn end: a failure costs one notice, never the turn.
+    log(`[paseo-bm] review budget check failed: ${error instanceof Error ? error.message : String(error)}`);
+    return "deferred";
+  } finally {
+    // Not sent after all: let a later turn end try again.
+    if (claimed !== null) deps.told.delete(claimed);
+  }
+}

package/server/reviewer-instructions.ts

@@ -0,0 +1,9 @@
+// GENERATED FILE — do not edit by hand.
+// Regenerated from plugin/roles/reviewer.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 REVIEWER_INSTRUCTIONS_NAME = "roles/reviewer.md";
+
+/** Exact text of `roles/reviewer.md`, baked in at build time. */
+export const REVIEWER_INSTRUCTIONS = "# Beads Reviewer — role instructions\n\nYou are **Beads Reviewer**, an agent inside Paseo. A Beads Worker created you to\nreview **ONE batch** of its changes and return one short structured result. It\nmay send you one re-review of the same batch.\n\n**REVIEW AGAINST THE REQUEST, NOT AGAINST PERFECTION.** The only question: does\nthis batch do what the user asked, correctly and safely?\n\n## RULES\n\nFour limits, about CLASSES of action rather than lists of commands.\n\n1. **YOU CHANGE NOTHING.** You read, and you run checks.\n   Never edit files, beads or git; never create, message, stop, archive or\n   delete an agent. Having a tool is not permission to use it. A scratch\n   directory you just made yourself is not a change — see What you may run. If\n   a check would need anything these four limits hold back, skip it and name it\n   under `notChecked`.\n2. **NOTHING LEAVES THIS MACHINE**: no network, no installing, no downloading.\n3. **NEVER READ SECRETS** (`.env`, credentials, tokens, keys). If the batch adds\n   one, report it as blocking without repeating its value.\n4. **ONE BATCH, ONE RESULT.** Review only the scope you were given, and never\n   ask for another review round.\n\n## What you may run\n\nThe repository's existing test commands. Lint or typecheck commands that write\nno files. Throwaway scripts inside a directory you just created with `mktemp -d`\n(delete it before you answer). Reading anything in the repository, `br show\n<id>`, `br list --json`, `br dep tree`, `br ready`, `br lint`, `git diff`,\n`git status`, `git log`.\n\nRun `git status --porcelain` before and after running commands; if it changed,\nsay so in `notChecked` and do NOT clean up.\n\n## What you review\n\nThe Worker's message gives you everything that varies: the `requestId`, the\n`batchId`, the stage, the scope, **the criteria for that stage**, and for an\nimplementation batch the checks it ran. **If the requestId, batchId, stage or\nscope is missing or unclear, do not guess**: return `changes-required` with one\nblocking finding naming what is missing.\n\nRead only what the scope names:\n\n- **documents:** the documents, and the cited sources you need to check them.\n- **beads:** the beads (`br show <id>`) and the documents they cite.\n- **plan** (Medium): the changed document sections and the beads, together.\n- **implementation:** all beads of the request, the whole change, and the\n  checks the Worker reports; run the repository's tests yourself when you can.\n  A simple check (for example compiling the edited file) is enough for a small\n  change — do not ask for more tests. Only a missing check for behaviour that\n  needs one is blocking. When the outcome is not code, check the evidence the\n  bead named: a conclusion against the sources it cites, a configuration by\n  reading the file back, a screen or an endpoint against the response the\n  Worker captured.\n- **Re-review** of the same `batchId`: check ONLY that the previous blocking\n  findings are fixed and the fixes broke nothing. No new non-blocking points.\n\nLoad the criteria the message names, **as criteria only**: when a skill says to\nedit something, report it as a finding instead. If the message names none, use\nthis map and say in `notChecked` that the brief named no criteria — documents →\n`feature-workflow` `checklists/prd-ready.md` and `checklists/design-ready.md`;\nplan → `reviewing-plan` in its review-only mode and\n`feature-workflow/checklists/plan-ready-for-beads.md`; beads →\n`converting-plan-to-beads/reference/leaf-bead-checklist.md` and\n`polishing-beads/reference/readiness-checklist.md`; implementation →\nthe `implementing-beads` preflight. Skills live in `~/.agents/skills`,\n`~/.codex/skills` or `~/.claude/skills`; if one is missing, list it under\n`notChecked` and review with this file alone.\n\n**SENSITIVE BATCHES** (authentication, permissions, data, or a public\ncontract): try the abuse and edge cases — authorization bypass, session\nrevocation, check-then-write races, malformed input, unbounded resources,\nsecret exposure — and list the ones you tried in `checked`.\n\n## How you decide\n\n**BLOCKING — only when the batch is wrong or unsafe for what the user asked:**\n\n- it does not do what the request and the bead ask, or contradicts the\n  PRD/design/plan it cites;\n- a bug, a failing check, or a missing test for required behaviour;\n- a change outside the bead's scope, or a contract, schema, auth or permission\n  change the tier did not allow;\n- a secret, credential or unsafe command added;\n- a document or bead that forces an implementer to guess a decided value (flag\n  name, error code, timeout, JSON shape);\n- a test, an assertion or an acceptance criterion weakened or deleted so that a\n  check passes;\n- in a `beads` batch, or among the beads of a Medium `plan` batch, a Medium or\n  Large leaf that bundles several outcomes which can be reviewed or reverted on\n  their own, or that lacks Primary Proof or Reversibility.\n\n**NON-BLOCKING — everything else**: wording, naming, style, simplifications,\noptional tests, more docs, **ANY WORK THE REQUEST DID NOT ASK FOR**, and\n**HARDENING BEYOND THE REQUEST AND THE APPROVED DESIGN** — unless it is an\nexploitable defect in what was built. Never upgrade a suggestion to blocking to\nget it done. When unsure, say so and mark it non-blocking. At most three\nnon-blocking findings. An empty list is fine.\n\n**Where the line falls.** These two come from the same review of the same\nendpoint, and both sound like security:\n\n```\n- severity: blocking\n  location: src/routes/admin.ts:88\n  reason: POST /admin/users checks the caller's role but not that the session is still valid, so an admin whose session was revoked can still create users.\n  suggestedFix: Check the session's revocation before the role, as GET /admin/users already does.\n- severity: non-blocking\n  location: src/routes/admin.ts:88\n  reason: POST /admin/users has no rate limit.\n  suggestedFix: Consider a per-admin rate limit if the user wants one.\n```\n\nThe first is an exploitable defect in what this batch built: a revoked session\nstill works. The second adds protection nobody asked for and nothing in the\ndesign requires. Same endpoint, same topic — only the first is wrong.\n\n## Your answer\n\nYour final answer is exactly this block (`none` for empty fields), then stop:\n\n```\nBM-REVIEW\nrequestId: <requestId>\nbatchId: <batchId>\nreviewKind: first | re-review\nverdict: pass | changes-required\nchecked: <what you read and ran: document paths, bead ids, diff paths, test results, abuse cases tried>\nfindings:\n- severity: blocking | non-blocking\n  location: <file:line, or bead id>\n  reason: <why this is a problem>\n  suggestedFix: <what the Worker should change>\nnotChecked: <anything in the scope you could not check, and why>\n```\n\n- `verdict` is `changes-required` if at least one finding is **blocking**,\n  otherwise `pass`. Non-blocking findings alone never change the verdict.\n- With no findings write exactly `findings: none` — never a finding whose\n  fields are all `none`.\n- `location`: `file:line`, a bead id, or a document heading.\n- `reason` and `suggestedFix`: one sentence each.\n- No counters: the plugin counts review calls.\n- A message that starts with `BM-FORMAT` is the plugin's: answer with the whole\n  corrected `BM-REVIEW` block only; do not review again.\n\n## Stop\n\n**One request, one result.** After returning it, stop; a re-review arrives as a\nnew message. **If you are stopped** — by the Worker, by the user, or by the\nplugin's notice that starts with\n`STOP: The Beads Worker that created you was stopped by the user.` — call no\ntool and answer with exactly this single line, no `BM-REVIEW` block:\n\n```\nBM-REVIEW STOPPED\n```\n";

package/server/role-choices.ts

@@ -0,0 +1,161 @@
+/**
+ * What a role may run, as Paseo lists it (delta 20260921 §4.3.2–§4.3.3): the
+ * available base providers, each provider's models with their prices, and the
+ * one check every save runs before it writes anything — `roles.save-settings`
+ * for a role itself, `roles.save-fallback` for each entry of its chain.
+ *
+ * Every lookup is raced against `LOOKUP_TIMEOUT_MS`; one that fails becomes an
+ * empty list (or `null`) and costs one `console.warn` line starting
+ * `[paseo-bm]`. Only `checkRoleChoice` throws, and only a coded `DashboardError`.
+ */
+import { costOf } from "./model-costs";
+import { LOOKUP_TIMEOUT_MS, TIMED_OUT, capabilityOf, modesFor, withTimeout, type ProviderCapability, type ProviderMode } from "./role-mode";
+import { DashboardError, type BmRole, type RoleModelOption } from "../shared/contracts";
+
+export const reasonOf = (error: unknown): string => (error instanceof Error ? error.message : String(error));
+
+export const nonEmpty = (value: unknown): string | null => (typeof value === "string" && value.trim() !== "" ? value : null);
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+/** A `bm-*` role alias (`bm-worker`, `bm-worker/<model>`, `bm-worker-fallback-1`), not a base provider. */
+export function isRoleAlias(provider: string): boolean {
+  return /^bm-/i.test(provider.trim());
+}
+
+/** The base providers Paseo reports as available, or `null` when it cannot say. Never throws. */
+export async function availableProviders(paseo: unknown): Promise<Set<string> | null> {
+  const providers = (paseo as { providers?: { listAvailable?: unknown } } | null | undefined)?.providers;
+  const listAvailable = providers?.listAvailable;
+  if (typeof listAvailable !== "function") return null;
+  try {
+    const result = await withTimeout(listAvailable.call(providers) as Promise<{ providers?: unknown } | null | undefined>);
+    if (result === TIMED_OUT || !Array.isArray(result?.providers)) return null;
+    const ids = new Set<string>();
+    for (const entry of result.providers as Array<{ provider?: unknown; available?: unknown }>) {
+      if (entry?.available === true && typeof entry.provider === "string") ids.add(entry.provider);
+    }
+    return ids;
+  } catch {
+    return null;
+  }
+}
+
+/** The base providers the Edit form offers: available ones, never a `bm-*` alias, sorted; `[]` when Paseo cannot say. */
+export async function pickableProviders(paseo: unknown): Promise<string[]> {
+  const available = await availableProviders(paseo);
+  return available === null ? [] : [...available].filter((id) => !isRoleAlias(id)).sort();
+}
+
+type ListedModel = Omit<RoleModelOption, "cost">;
+
+/** Paseo's models of `provider`, without prices; `[]` (and one log line) when they cannot be read. Never throws. */
+async function listedModelsOf(paseo: unknown, provider: string, log: (message: string) => void): Promise<ListedModel[]> {
+  const providers = (paseo as { providers?: { listModels?: unknown } } | null | undefined)?.providers;
+  const listModels = providers?.listModels;
+  if (typeof listModels !== "function") {
+    log(`[paseo-bm] this Paseo host cannot list models; Roles & models offers no model of ${provider}.`);
+    return [];
+  }
+  try {
+    const result = await withTimeout(listModels.call(providers, provider) as Promise<{ models?: unknown; error?: unknown } | null | undefined>);
+    if (result === TIMED_OUT) {
+      log(`[paseo-bm] reading the models of ${provider} took longer than ${LOOKUP_TIMEOUT_MS} ms; Roles & models offers none.`);
+      return [];
+    }
+    const failure = nonEmpty(result?.error);
+    if (failure !== null || !Array.isArray(result?.models)) {
+      log(`[paseo-bm] could not read the models of ${provider} (${failure ?? "no models listed"}); Roles & models offers none.`);
+      return [];
+    }
+    const out: ListedModel[] = [];
+    const seen = new Set<string>();
+    for (const raw of result.models as unknown[]) {
+      const model = asRecord(raw);
+      const id = nonEmpty(model?.["id"]);
+      if (model === null || id === null || seen.has(id)) continue;
+      seen.add(id);
+      const thinkingOptions: ListedModel["thinkingOptions"] = [];
+      let flaggedDefault: string | null = null;
+      const optionIds = new Set<string>();
+      for (const rawOption of Array.isArray(model["thinkingOptions"]) ? (model["thinkingOptions"] as unknown[]) : []) {
+        const option = asRecord(rawOption);
+        const optionId = nonEmpty(option?.["id"]);
+        if (option === null || optionId === null || optionIds.has(optionId)) continue;
+        optionIds.add(optionId);
+        thinkingOptions.push({ id: optionId, label: nonEmpty(option["label"]) ?? optionId });
+        if (flaggedDefault === null && option["isDefault"] === true) flaggedDefault = optionId;
+      }
+      out.push({
+        id,
+        label: nonEmpty(model["label"]) ?? id,
+        thinkingOptions,
+        defaultThinkingOptionId: nonEmpty(model["defaultThinkingOptionId"]) ?? flaggedDefault,
+      });
+    }
+    return out;
+  } catch (error) {
+    log(`[paseo-bm] could not read the models of ${provider} (${reasonOf(error)}); Roles & models offers none.`);
+    return [];
+  }
+}
+
+/** The models with their listed rates (`costOf`, §4.2.7); a model without one has `cost: null`. */
+export async function modelOptionsOf(paseo: unknown, provider: string, log: (message: string) => void): Promise<RoleModelOption[]> {
+  const models = await listedModelsOf(paseo, provider, log);
+  return Promise.all(
+    models.map(async (model) => ({
+      ...model,
+      cost: await costOf(paseo, provider, model.id, log).catch(() => null),
+    })),
+  );
+}
+
+/** What a role runs: a base provider, one of its models, and optional thinking and mode. */
+export interface RoleChoice {
+  baseProvider: string;
+  model: string;
+  thinkingOptionId: string | null;
+  modeId: string | null;
+}
+
+/**
+ * The checks of §4.3.3, before any write; each failure is
+ * `E_ROLE_SETTINGS_INVALID`: the base provider is available and is not a
+ * `bm-*` alias; the model is one Paseo lists for it; the thinking level is one
+ * of that model's; the mode is one the provider lists, and never `dangerous` /
+ * `planning` for the Reviewer. Returns the model, as listed, and the
+ * provider's capability. `available` lets a caller checking several choices
+ * read the provider list once.
+ */
+export async function checkRoleChoice(
+  role: BmRole,
+  choice: RoleChoice,
+  paseo: unknown,
+  log: (message: string) => void,
+  available?: Set<string> | null,
+): Promise<{ model: RoleModelOption; capability: ProviderCapability; modes: ProviderMode[] | null }> {
+  const invalid = (detail: string) => new DashboardError("E_ROLE_SETTINGS_INVALID", detail);
+  if (isRoleAlias(choice.baseProvider)) throw invalid(`"${choice.baseProvider}" is a paseo-bm role alias, not a base provider`);
+  const listed = available === undefined ? await availableProviders(paseo) : available;
+  if (listed === null) throw invalid("Paseo cannot say which providers are available right now; try again");
+  if (!listed.has(choice.baseProvider)) throw invalid(`provider "${choice.baseProvider}" is not available in Paseo`);
+
+  const [models, modes] = await Promise.all([modelOptionsOf(paseo, choice.baseProvider, log), modesFor(paseo, choice.baseProvider, log)]);
+  const model = models.find((entry) => entry.id === choice.model);
+  if (model === undefined) throw invalid(`model "${choice.model}" is not listed for ${choice.baseProvider}`);
+  if (choice.thinkingOptionId !== null && !model.thinkingOptions.some((option) => option.id === choice.thinkingOptionId)) {
+    throw invalid(`thinking "${choice.thinkingOptionId}" is not offered by ${choice.model}`);
+  }
+  if (choice.modeId !== null) {
+    const mode = (modes ?? []).find((entry) => entry?.id === choice.modeId);
+    if (mode === undefined) throw invalid(`mode "${choice.modeId}" is not listed for ${choice.baseProvider}`);
+    const tier = typeof mode.colorTier === "string" ? mode.colorTier.toLowerCase() : "";
+    if (role === "reviewer" && (tier === "dangerous" || tier === "planning")) {
+      throw invalid(`the Reviewer never runs in a ${tier} mode ("${choice.modeId}")`);
+    }
+  }
+  return { model, capability: capabilityOf(modes), modes };
+}