paseo-bm-plugin 0.0.0-placeholder.0

package/server/fallback-rpc.ts

@@ -0,0 +1,306 @@
+/**
+ * The fallback card's server side (delta 20260921 §4.4.6, §4.4.10, REQ-065 c).
+ *
+ * - `BM-FALLBACK`: a new `pending` incident with a `managerId` is told to that
+ *   Manager's chat through the notice queue (the Manager may be running, F13),
+ *   and so is every later decision, with its new `status` and `replacement`.
+ *   The chat renders the block as a card; the card's state always comes from
+ *   `fallback.incidents`, never from the text.
+ * - `fallback.incidents`: the recorded incidents, filtered by workspace or ids.
+ * - `fallback.act`: `dismiss` ("I'll handle it") marks the incident
+ *   `dismissed` and touches no agent. `switch` (§4.4.7) and `wait` (§4.4.9)
+ *   are handed in by the modules that implement them.
+ *
+ * Handlers throw only coded `DashboardError`s; the notice never throws.
+ */
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { onFallbackIncident, readIncidents, updateIncidents } from "./fallback-state";
+import { FALLBACK_NOTICE_MARKER } from "./notices";
+import { enqueue as defaultEnqueue, type NoticeOutcome, type NoticePaseo } from "./notice-queue";
+import { providerId } from "./provider-id";
+import { asRecord, nonEmpty, reasonOf } from "./role-choices";
+import { installHomeOf } from "./role-extras";
+import { TIMED_OUT, withTimeout } from "./role-mode";
+import { FALLBACK_CLASS_LABELS } from "../shared/bm-fallback";
+import { DashboardError, fallbackActRpc, fallbackIncidentsRpc, type FallbackActInput, type FallbackIncident } from "../shared/contracts";
+
+/** Longest message line of the notice. */
+export const NOTICE_MESSAGE_CHARS = 300;
+
+const defaultLog = (message: string): void => console.warn(message);
+
+/**
+ * The `BM-FALLBACK` block of an incident, word for word (agent-facing, so
+ * English). `baseOf` gives the base provider an alias extends (`null` when
+ * unknown, written `unknown`). `closing` replaces the Manager's closing line —
+ * the Worker of a switched Reviewer gets its instructions there (§4.5.1).
+ */
+export function fallbackNotice(incident: FallbackIncident, baseOf: (alias: string) => string | null, closing?: string): string {
+  const alias = providerId(incident.agentProvider) ?? incident.agentProvider;
+  const message = incident.message.replace(/\s+/g, " ").trim().slice(0, NOTICE_MESSAGE_CHARS);
+  const candidate =
+    incident.candidate === null
+      ? "none"
+      : `${incident.candidate.alias} · ${incident.candidate.baseProvider} · ${incident.candidate.model} · thinking ${incident.candidate.thinkingOptionId ?? "provider default"}`;
+  return [
+    FALLBACK_NOTICE_MARKER,
+    `incident: ${incident.id}`,
+    `role: ${incident.role}`,
+    `agent: ${incident.agentId}`,
+    `requestId: ${incident.requestId ?? "none"}`,
+    `status: ${incident.status}`,
+    `class: ${FALLBACK_CLASS_LABELS[incident.class]}`,
+    `provider: ${alias} (${baseOf(alias) ?? "unknown"}) · ${incident.agentModel ?? "unknown"}`,
+    `message: ${message === "" ? "none" : message}`,
+    `resetsAt: ${incident.resetsAt ?? "unknown"}`,
+    `candidate: ${candidate}`,
+    `replacement: ${incident.replacementId ?? "none"}`,
+    "",
+    closing ??
+      `The ${incident.role} stopped because of its provider plan. The user decides on the card in this chat. Tell the user in one line; do not create an agent yourself.`,
+  ].join("\n");
+}
+
+/** The `extends` of every alias, from one `config.get()` under the lookup budget; `{}` when unreadable. Never throws. */
+export async function aliasBases(paseo: unknown): Promise<Record<string, string>> {
+  const config = (paseo as { config?: { get?: unknown } } | null | undefined)?.config;
+  if (typeof config?.get !== "function") return {};
+  try {
+    const result = await withTimeout(config.get.call(config) as Promise<{ config?: unknown } | null | undefined>);
+    if (result === TIMED_OUT) return {};
+    const out: Record<string, string> = {};
+    for (const [id, entry] of Object.entries(asRecord(asRecord(result?.config)?.["providers"]) ?? {})) {
+      const base = nonEmpty(asRecord(entry)?.["extends"]);
+      if (base !== null) out[id] = base;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+export interface FallbackNoticeDeps {
+  enqueue?: (targetId: string, kind: string, text: string, paseo?: NoticePaseo) => Promise<NoticeOutcome>;
+  log?: (message: string) => void;
+}
+
+/**
+ * Tells the incident's Manager chat (kind `BM-FALLBACK`, through the notice
+ * queue). No `managerId` → nothing (only the pill shows it). Never throws.
+ */
+export async function notifyFallback(incident: FallbackIncident, paseo: unknown, deps: FallbackNoticeDeps = {}): Promise<NoticeOutcome | null> {
+  if (incident.managerId === null) return null;
+  const log = deps.log ?? defaultLog;
+  try {
+    const bases = await aliasBases(paseo);
+    const text = fallbackNotice(incident, (alias) => bases[alias] ?? null);
+    return await (deps.enqueue ?? defaultEnqueue)(incident.managerId, FALLBACK_NOTICE_MARKER, text, paseo as NoticePaseo);
+  } catch (error) {
+    log(`[paseo-bm] telling ${incident.managerId} about fallback incident ${incident.id} failed: ${reasonOf(error)}`);
+    return null;
+  }
+}
+
+export interface FallbackRpcDeps extends FallbackNoticeDeps {
+  /** The install home; the plugin looks it up, tests pass one. */
+  home?: string | null;
+  now?: () => Date;
+}
+
+/** The install home, raced against the lookup budget. */
+async function homeOf(paseo: unknown, deps: FallbackRpcDeps): Promise<string | null> {
+  if (deps.home !== undefined) return deps.home;
+  const found = await withTimeout(installHomeOf(paseo));
+  return found === TIMED_OUT ? null : found;
+}
+
+/** Handler body of `fallback.incidents`: oldest first; an unreadable file or unknown home reads as none. */
+export async function handleFallbackIncidents(
+  input: { workspaceId?: string; ids?: string[] },
+  paseo: unknown,
+  deps: FallbackRpcDeps = {},
+): Promise<{ incidents: FallbackIncident[] }> {
+  const home = await homeOf(paseo, deps);
+  if (home === null) return { incidents: [] };
+  const ids = input?.ids === undefined ? null : new Set(input.ids);
+  const incidents = readIncidents(home, deps.log ?? defaultLog).incidents.filter(
+    (incident) => (input?.workspaceId === undefined || incident.workspaceId === input.workspaceId) && (ids === null || ids.has(incident.id)),
+  );
+  return { incidents };
+}
+
+/** One of the card's actions on a `pending` incident; returns the incident as written. */
+export type FallbackAction = (incident: FallbackIncident, paseo: unknown, deps: FallbackRpcDeps) => Promise<FallbackIncident>;
+
+/**
+ * Moves one incident from `pending` under the incidents mutex: `change` gets
+ * it and returns its new state. Throws `E_FALLBACK_NOT_FOUND` (unknown id, or
+ * no usable incidents file) and `E_FALLBACK_NOT_PENDING`.
+ */
+export async function decidePending(
+  home: string,
+  incidentId: string,
+  change: (incident: FallbackIncident) => FallbackIncident,
+  log: (message: string) => void = defaultLog,
+): Promise<FallbackIncident> {
+  let decided: FallbackIncident | null = null;
+  const written = await updateIncidents(
+    home,
+    (incidents) => {
+      const index = incidents.findIndex((incident) => incident.id === incidentId);
+      if (index === -1) throw new DashboardError("E_FALLBACK_NOT_FOUND", `no fallback incident ${incidentId}`);
+      const current = incidents[index]!;
+      if (current.status !== "pending") {
+        throw new DashboardError("E_FALLBACK_NOT_PENDING", `incident ${incidentId} is ${current.status}, not pending`);
+      }
+      decided = change(current);
+      return incidents.map((incident, at) => (at === index ? decided! : incident));
+    },
+    log,
+  );
+  if (written === null || decided === null) throw new DashboardError("E_FALLBACK_NOT_FOUND", "the fallback incidents file cannot be read");
+  return decided;
+}
+
+/** `dismiss` ("I'll handle it", §4.4.10): `dismissed`, no agent touched. */
+export const dismissIncident: FallbackAction = async (incident, _paseo, deps) => {
+  const home = await homeOf(_paseo, deps);
+  if (home === null) throw new DashboardError("E_FALLBACK_NOT_FOUND", "paseo-bm cannot find its install home");
+  const now = (deps.now ?? (() => new Date()))().toISOString();
+  return decidePending(home, incident.id, (current) => ({ ...current, status: "dismissed", decidedAt: now }), deps.log ?? defaultLog);
+};
+
+export interface FallbackActions {
+  switch?: FallbackAction;
+  wait?: FallbackAction;
+  /** Sends a switched Reviewer's instructions to its Worker again (§4.5.1, §7). */
+  resend?: FallbackAction;
+}
+
+let actionQueue: Promise<unknown> = Promise.resolve();
+
+/** Runs `work` after every card action queued before it; a failure does not block the next one. */
+function oneActionAtATime<T>(work: () => Promise<T>): Promise<T> {
+  const run = actionQueue.then(work, work);
+  actionQueue = run.catch(() => undefined);
+  return run;
+}
+
+/**
+ * Handler body of `fallback.act`. Card actions run ONE AT A TIME (review b6):
+ * the incident is read and checked `pending` inside that lock, and the action
+ * runs to its end before the next one reads it. So a Switch can never create a
+ * Worker for an incident a concurrent Wait or Dismiss already decided, and a
+ * second action on the same incident always finds it decided. Then the Manager
+ * chat is told the new status. An action this build does not have yet fails
+ * with its coded error.
+ */
+export function handleFallbackAct(
+  input: FallbackActInput,
+  paseo: unknown,
+  deps: FallbackRpcDeps & { actions?: FallbackActions } = {},
+): Promise<{ incident: FallbackIncident }> {
+  return oneActionAtATime(async () => {
+    const home = await homeOf(paseo, deps);
+    if (home === null) throw new DashboardError("E_FALLBACK_NOT_FOUND", "paseo-bm cannot find its install home");
+    const found = readIncidents(home, deps.log ?? defaultLog).incidents.find((incident) => incident.id === input.incidentId);
+    if (found === undefined) throw new DashboardError("E_FALLBACK_NOT_FOUND", `no fallback incident ${input.incidentId}`);
+    const scoped = { ...deps, home };
+    if (input.action === "resend") {
+      // Only a switched Reviewer whose replacement never appeared; the Manager chat already shows `switched`.
+      if (found.role !== "reviewer" || found.status !== "switched" || found.replacementId !== null) {
+        throw new DashboardError("E_FALLBACK_NOT_PENDING", `incident ${found.id} has nothing to resend`);
+      }
+      if (deps.actions?.resend === undefined) throw new DashboardError("E_FALLBACK_CREATE_FAILED", "resending is not available in this build");
+      return { incident: await deps.actions.resend(found, paseo, scoped) };
+    }
+    if (found.status !== "pending") throw new DashboardError("E_FALLBACK_NOT_PENDING", `incident ${found.id} is ${found.status}, not pending`);
+    let action: FallbackAction;
+    if (input.action === "dismiss") action = dismissIncident;
+    else if (input.action === "switch") {
+      if (deps.actions?.switch === undefined) throw new DashboardError("E_FALLBACK_CREATE_FAILED", "switching is not available in this build");
+      action = deps.actions.switch;
+    } else {
+      if (deps.actions?.wait === undefined) throw new DashboardError("E_FALLBACK_NO_RESET", "waiting for the reset is not available in this build");
+      action = deps.actions.wait;
+    }
+    const incident = await action(found, paseo, scoped);
+    await notifyFallback(incident, paseo, deps);
+    return { incident };
+  });
+}
+
+/** A reset this close is waited for rather than switched away from (§4.6, REQ-067 b). */
+export const AUTO_WAIT_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * What the `auto` policy chooses for a new `pending` incident (§4.6): `wait`
+ * when the reset is known and at most 30 minutes away (a reset already past
+ * counts), else `switch` when there is a candidate, else nothing — the
+ * incident stays pending, as with "Ask me".
+ */
+export function autoActionOf(incident: FallbackIncident, now: Date): "wait" | "switch" | null {
+  const resetsAt = incident.resetsAt === null ? Number.NaN : Date.parse(incident.resetsAt);
+  if (!Number.isNaN(resetsAt) && resetsAt - now.getTime() <= AUTO_WAIT_WINDOW_MS) return "wait";
+  return incident.candidate === null ? null : "switch";
+}
+
+/**
+ * Runs the `auto` policy's choice for a new incident through `fallback.act`,
+ * so it takes the same lock, the same checks and the same notices as a click.
+ * Returns true when an action ran (its notice went out, or the failure's did);
+ * false when nothing was chosen and the incident stays pending. Never throws.
+ */
+export async function decideAutomatically(
+  incident: FallbackIncident,
+  paseo: unknown,
+  deps: FallbackRpcDeps & { actions: FallbackActions },
+): Promise<boolean> {
+  const log = deps.log ?? defaultLog;
+  const action = autoActionOf(incident, (deps.now ?? (() => new Date()))());
+  if (action === null) return false;
+  try {
+    await handleFallbackAct({ incidentId: incident.id, action }, paseo, deps);
+  } catch (error) {
+    log(`[paseo-bm] the Auto switch policy could not ${action} for incident ${incident.id}: ${reasonOf(error)}`);
+    // The card shows what became of it; the chat is told the state it is in now.
+    const home = await homeOf(paseo, deps);
+    const now = home === null ? undefined : readIncidents(home, log).incidents.find((entry) => entry.id === incident.id);
+    await notifyFallback(now ?? incident, paseo, deps);
+  }
+  return true;
+}
+
+/**
+ * Registers `fallback.incidents` and `fallback.act`, and tells the Manager
+ * chat about every new `pending` incident — after the `auto` policy has run
+ * its choice, if the role has it (§4.6), so the chat hears the chosen state
+ * once. `onPaseo` hears each handler's SDK handle (the wait timers are set
+ * again from it, §4.4.9). Returns the remover of that listener.
+ */
+export function registerFallbackRpcs(
+  server: PluginServerContext,
+  actions: FallbackActions = {},
+  options: { onPaseo?: (paseo: unknown) => void } = {},
+): () => void {
+  const seen = (paseo: unknown) => {
+    try {
+      options.onPaseo?.(paseo);
+    } catch {
+      // Setting the wait timers again never fails a card action.
+    }
+  };
+  server.handle(fallbackIncidentsRpc, (input, context) => {
+    seen(context.paseo);
+    return handleFallbackIncidents(input, context.paseo);
+  });
+  server.handle(fallbackActRpc, (input, context) => {
+    seen(context.paseo);
+    return handleFallbackAct(input, context.paseo, { actions });
+  });
+  return onFallbackIncident(async (incident, paseo, context) => {
+    if (incident.status !== "pending") return;
+    if (context?.policy === "auto" && (await decideAutomatically(incident, paseo, { actions, home: context.home }))) return;
+    await notifyFallback(incident, paseo);
+  });
+}

package/server/fallback-settings.ts

@@ -0,0 +1,322 @@
+/**
+ * Fallback chains: what the user saves for a role that hits its plan limit
+ * (delta 20260921 §4.4.1–§4.4.3, REQ-065 f; ADR-008 D2, D4).
+ *
+ * A chain has a policy (`ask` shows a card, `off` does nothing, `auto` decides
+ * at once by the card's rules — phase 2a-18, §4.6) and 0–3 entries. It lives
+ * in two places, on purpose:
+ *
+ * - entry `n` runs on the alias `bm-<role>-fallback-<n>` in Paseo's config,
+ *   so the `agent.create` hook recognises the role (`roleOfProvider`). Written
+ *   through `config-writer.ts`, so the same `revision` guards it as a role save;
+ * - the entry's model, thinking and mode, and the policy, live in the user's
+ *   own file `<install home>/role-fallback.json`: user data like
+ *   `role-extras.json` (F9) — mode 0600, temp file then rename, symlink
+ *   refused, no hash in `install.json`, never touched by an update, `--prune`
+ *   or uninstall.
+ *
+ * Aliases are written first, then the file. A file write that fails after the
+ * aliases is reported; the alias left behind is harmless (no entry uses it)
+ * and the next save cleans it up. A file that does not parse is never
+ * overwritten: the save is refused until the user fixes or deletes it, so a
+ * hand-edited `patterns` block is never lost.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { canonicalJson, readRoleConfig, writeRoleConfig, type ConfigPaseo } from "./config-writer";
+import { TRACES_DIR_NAME } from "./install-home";
+import { costOf } from "./model-costs";
+import { asRecord, availableProviders, checkRoleChoice, nonEmpty, reasonOf } from "./role-choices";
+import { installHomeOf } from "./role-extras";
+import { TIMED_OUT, capabilityOf, modesFor, withTimeout, type ProviderCapability } from "./role-mode";
+import { writeStoreFileAtomically } from "./trace-store";
+import { FALLBACK_ROLES, MAX_FALLBACK_ENTRIES, fallbackAlias, fallbackAliasOf, type FallbackRole } from "../shared/fallback";
+import {
+  DashboardError,
+  fallbackEntryInputSchema,
+  type BmRole,
+  type FallbackEntryInput,
+  type FallbackSettings,
+  type RolesSaveFallbackInput,
+} from "../shared/contracts";
+
+export const ROLE_FALLBACK_FILE = "role-fallback.json";
+
+const chainSchema = z.object({
+  policy: z.enum(["ask", "off", "auto"]),
+  entries: z.array(fallbackEntryInputSchema).max(MAX_FALLBACK_ENTRIES),
+});
+
+/** `role-fallback.json` (§4.4.2). `patterns` is edited by hand only and shared by every role. */
+export const roleFallbackFileSchema = z.object({
+  version: z.literal(1),
+  roles: z
+    .object({ manager: chainSchema.optional(), worker: chainSchema.optional(), reviewer: chainSchema.optional() })
+    .default({}),
+  patterns: z
+    .object({
+      L1: z.array(z.string()).optional(),
+      L2: z.array(z.string()).optional(),
+      L3: z.array(z.string()).optional(),
+      L4: z.array(z.string()).optional(),
+      L5: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+export type RoleFallbackFile = z.infer<typeof roleFallbackFileSchema>;
+export type FallbackChain = z.infer<typeof chainSchema>;
+
+/** A role the file does not mention: ask, with no entry (the card still offers Wait and "I'll handle it"). */
+export const DEFAULT_CHAIN: FallbackChain = { policy: "ask", entries: [] };
+
+const ROLE_LABELS: Readonly<Record<BmRole, string>> = { manager: "Manager", worker: "Worker", reviewer: "Reviewer" };
+
+const defaultLog = (message: string): void => console.warn(message);
+
+export interface RoleFallbackRead {
+  /** The file as parsed, or the defaults when it is missing or invalid. */
+  file: RoleFallbackFile;
+  /** The JSON object as read, so a save keeps every key it does not own; `null` without a valid file. */
+  raw: Record<string, unknown> | null;
+  /** Why the file could not be used; `null` when it is valid or simply missing. */
+  error: string | null;
+}
+
+const emptyFile = (): RoleFallbackFile => ({ version: 1, roles: {} });
+
+/** Reads `role-fallback.json` in `home`. Never throws: an invalid file costs one log line and reads as the defaults. */
+export function readRoleFallback(home: string, log: (message: string) => void = defaultLog): RoleFallbackRead {
+  const path = join(home, ROLE_FALLBACK_FILE);
+  const invalid = (reason: string): RoleFallbackRead => {
+    log(`[paseo-bm] ${path} is not usable (${reason}); fallback chains use the defaults until it is fixed or deleted.`);
+    return { file: emptyFile(), raw: null, error: reason };
+  };
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return { file: emptyFile(), raw: null, error: null };
+    return invalid(reasonOf(error));
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return invalid(`not JSON: ${reasonOf(error)}`);
+  }
+  const result = roleFallbackFileSchema.safeParse(parsed);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    return invalid(issue === undefined ? "unexpected content" : `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+  }
+  return { file: result.data, raw: asRecord(parsed), error: null };
+}
+
+/** A role's chain in the file, or the defaults. */
+export function chainOf(file: RoleFallbackFile, role: BmRole): FallbackChain {
+  const chain = file.roles[role];
+  return chain === undefined ? { ...DEFAULT_CHAIN, entries: [] } : chain;
+}
+
+/** True when the file carries at least one detection pattern of its own. */
+function patternsFromFile(file: RoleFallbackFile): boolean {
+  return Object.values(file.patterns ?? {}).some((list) => Array.isArray(list) && list.length > 0);
+}
+
+/** Writes the file: atomic, 0600, no symlink on the way. Throws `E_ROLE_SETTINGS_WRITE_FAILED`. */
+function writeRoleFallback(home: string, body: Record<string, unknown>): void {
+  try {
+    writeStoreFileAtomically({ tracesDir: join(home, TRACES_DIR_NAME) }, join(home, ROLE_FALLBACK_FILE), `${JSON.stringify(body, null, 2)}\n`);
+  } catch (error) {
+    throw new DashboardError("E_ROLE_SETTINGS_WRITE_FAILED", `could not write ${ROLE_FALLBACK_FILE}: ${reasonOf(error)}`, { cause: error });
+  }
+}
+
+/**
+ * A chain as Roles & models shows it: each entry with its alias, the
+ * capability of its provider and its listed price. Lookups that fail give
+ * `unknown` / `null` and one log line; never throws.
+ */
+export async function fallbackSettingsOf(
+  role: BmRole,
+  chain: FallbackChain,
+  fromFile: boolean,
+  paseo: unknown,
+  log: (message: string) => void = defaultLog,
+): Promise<FallbackSettings> {
+  const capabilities = new Map<string, Promise<ProviderCapability>>();
+  const capabilityFor = (provider: string): Promise<ProviderCapability> => {
+    let known = capabilities.get(provider);
+    if (known === undefined) {
+      known = modesFor(paseo, provider, log).then(capabilityOf, () => "unknown" as const);
+      capabilities.set(provider, known);
+    }
+    return known;
+  };
+  const entries = await Promise.all(
+    chain.entries.map(async (entry, index) => ({
+      position: index + 1,
+      alias: fallbackAlias(role, index + 1),
+      baseProvider: entry.baseProvider,
+      model: entry.model,
+      thinkingOptionId: entry.thinkingOptionId,
+      modeId: entry.modeId,
+      capability: await capabilityFor(entry.baseProvider),
+      cost: await costOf(paseo, entry.baseProvider, entry.model, log).catch(() => null),
+    })),
+  );
+  return { role, policy: chain.policy, entries, patternsFromFile: fromFile };
+}
+
+export interface FallbackDeps {
+  log?: (message: string) => void;
+  /** Home directory for locating the install home (tests pass a temporary one). */
+  homedir?: () => string;
+  /** The install home itself, when the caller already knows it (`null`: none); otherwise it is looked up. */
+  home?: string | null;
+}
+
+/** The install home, raced against the lookup budget like every other read; `null` when unknown. Never throws. */
+async function homeOf(paseo: unknown, deps: FallbackDeps): Promise<string | null> {
+  if (deps.home !== undefined) return deps.home;
+  const found = await withTimeout(installHomeOf(paseo, deps.homedir === undefined ? {} : { homedir: deps.homedir }));
+  return found === TIMED_OUT ? null : found;
+}
+
+/**
+ * The `fallback` of `roles.settings`: the chain of every role in
+ * `FALLBACK_ROLES`, or `null` when none is offered. An install home that
+ * cannot be confirmed reads as the defaults (a save then reports it); an
+ * invalid file adds one warning.
+ */
+export async function fallbackForSettings(
+  paseo: unknown,
+  deps: FallbackDeps = {},
+): Promise<{ fallback: Partial<Record<FallbackRole, FallbackSettings>> | null; warnings: string[] }> {
+  if (FALLBACK_ROLES.length === 0) return { fallback: null, warnings: [] };
+  const log = deps.log ?? defaultLog;
+  const home = await homeOf(paseo, deps);
+  const read = home === null ? { file: emptyFile(), raw: null, error: null } : readRoleFallback(home, log);
+  const warnings =
+    read.error === null ? [] : [`${ROLE_FALLBACK_FILE} is not valid (${read.error}); fallback uses the defaults until you fix or delete it.`];
+  const fromFile = patternsFromFile(read.file);
+  const fallback: Partial<Record<FallbackRole, FallbackSettings>> = {};
+  for (const role of FALLBACK_ROLES) fallback[role] = await fallbackSettingsOf(role, chainOf(read.file, role), fromFile, paseo, log);
+  return { fallback, warnings };
+}
+
+let queue: Promise<unknown> = Promise.resolve();
+
+/** Runs `work` after every save queued before it; a failure does not block the next one. */
+function serialised<T>(work: () => Promise<T>): Promise<T> {
+  const run = queue.then(work, work);
+  queue = run.catch(() => undefined);
+  return run;
+}
+
+/** The alias entry of fallback `n` of `role` (§4.4.1): a Reviewer alias never gets Paseo tools (ADR-006 D3). */
+export function fallbackAliasEntry(role: BmRole, n: number, baseProvider: string): Record<string, unknown> {
+  return {
+    extends: baseProvider,
+    label: `${ROLE_LABELS[role]} (fallback ${n})`,
+    ...(role === "reviewer" ? {} : { paseoTools: { enabled: true } }),
+  };
+}
+
+/** True when `existing` already holds every key of `wanted` with the same value. */
+function holds(existing: unknown, wanted: Record<string, unknown>): boolean {
+  const entry = asRecord(existing);
+  return entry !== null && Object.entries(wanted).every(([key, value]) => canonicalJson(entry[key]) === canonicalJson(value));
+}
+
+/**
+ * Handler body of `roles.save-fallback` (§4.4.3). Runs every check before any
+ * write (`E_ROLE_SETTINGS_INVALID`): the role's chain is offered; the policy
+ * is `ask`, `off` or `auto` (§4.6); at most three entries; each entry passes the checks of a
+ * role save (the Reviewer's mode rule included); no two entries with the same
+ * provider and model; no entry equal to the role's own provider and model.
+ * Then the aliases (revision-checked, `E_ROLE_SETTINGS_CONFLICT` on a stale
+ * one) and the file. An entry on the role's own base provider is warned about,
+ * never refused.
+ */
+export function handleRolesSaveFallback(
+  input: RolesSaveFallbackInput,
+  paseo: unknown,
+  deps: FallbackDeps = {},
+): Promise<{ revision: string; fallback: FallbackSettings; warnings: string[] }> {
+  return serialised(async () => {
+    const log = deps.log ?? defaultLog;
+    const invalid = (detail: string) => new DashboardError("E_ROLE_SETTINGS_INVALID", detail);
+    const role = input.role;
+    if (!(FALLBACK_ROLES as readonly string[]).includes(role)) {
+      throw invalid(`fallback chains are not offered for the ${ROLE_LABELS[role] ?? String(role)} in this release`);
+    }
+    if (input.policy !== "ask" && input.policy !== "off" && input.policy !== "auto") throw invalid(`policy "${String(input.policy)}" is not a fallback policy`);
+    const entries: FallbackEntryInput[] = Array.isArray(input.entries) ? input.entries : [];
+    if (entries.length > MAX_FALLBACK_ENTRIES) throw invalid(`at most ${MAX_FALLBACK_ENTRIES} fallbacks per role, got ${entries.length}`);
+
+    const available = await availableProviders(paseo);
+    for (const entry of entries) await checkRoleChoice(role, entry, paseo, log, available);
+    const seen = new Set<string>();
+    for (const [index, entry] of entries.entries()) {
+      const key = JSON.stringify([entry.baseProvider, entry.model]);
+      if (seen.has(key)) throw invalid(`fallback ${index + 1} repeats ${entry.baseProvider} · ${entry.model}`);
+      seen.add(key);
+    }
+
+    const { config } = await readRoleConfig(paseo as ConfigPaseo);
+    const providers = asRecord(config.providers) ?? {};
+    const mainId = `bm-${role}`;
+    const mainBase = nonEmpty(asRecord(providers[mainId])?.["extends"]);
+    const mainProfile = (Array.isArray(config.agentProfiles) ? config.agentProfiles : []).find((profile) => profile?.["id"] === mainId);
+    const mainModel = nonEmpty(mainProfile?.["model"]);
+    const warnings: string[] = [];
+    for (const [index, entry] of entries.entries()) {
+      if (entry.baseProvider !== mainBase) continue;
+      if (entry.model === mainModel) throw invalid(`fallback ${index + 1} is the ${ROLE_LABELS[role]} itself (${entry.baseProvider} · ${entry.model})`);
+      warnings.push(`Fallback ${index + 1} runs on ${entry.baseProvider} like the ${ROLE_LABELS[role]} itself: it only helps when the limit is per model.`);
+    }
+
+    const home = await homeOf(paseo, deps);
+    if (home === null) {
+      throw new DashboardError("E_ROLE_SETTINGS_WRITE_FAILED", "paseo-bm cannot find its install home; run npx paseo-bm install, then save again");
+    }
+    const read = readRoleFallback(home, log);
+    if (read.error !== null) throw invalid(`${ROLE_FALLBACK_FILE} is not valid (${read.error}); fix or delete it, then save again`);
+
+    // Entry n on alias n, renumbered so n stays contiguous; aliases past the
+    // new chain are removed. Only what differs is sent.
+    const aliasWrites: Record<string, Record<string, unknown>> = {};
+    for (const [index, entry] of entries.entries()) {
+      const alias = fallbackAlias(role, index + 1);
+      const wanted = fallbackAliasEntry(role, index + 1, entry.baseProvider);
+      if (!holds(providers[alias], wanted)) aliasWrites[alias] = wanted;
+    }
+    const removals = Object.keys(providers).filter((id) => {
+      const found = fallbackAliasOf(id);
+      return found !== null && found.role === role && found.position > entries.length;
+    });
+    const written = await writeRoleConfig(paseo as ConfigPaseo, {
+      expectedRevision: input.revision,
+      providers: aliasWrites,
+      removeProviders: removals,
+    });
+
+    const chain: FallbackChain = {
+      policy: input.policy,
+      entries: entries.map((entry) => ({
+        baseProvider: entry.baseProvider,
+        model: entry.model,
+        thinkingOptionId: entry.thinkingOptionId,
+        modeId: entry.modeId,
+      })),
+    };
+    const raw = read.raw ?? {};
+    writeRoleFallback(home, { ...raw, version: 1, roles: { ...(asRecord(raw["roles"]) ?? {}), [role]: chain } });
+
+    const fallback = await fallbackSettingsOf(role, chain, patternsFromFile(read.file), paseo, log);
+    return { revision: written.revision, fallback, warnings };
+  });
+}