paseo-bm-plugin 0.0.0-placeholder.0

package/server/fallback-detect.ts

@@ -0,0 +1,183 @@
+/**
+ * Whether a finished turn ended on a provider-plan failure, and which class
+ * (delta 20260921 §4.4.4, REQ-065 a, b).
+ *
+ * Today the plugin ignores a failed turn (proposal M9): a Worker whose plan ran
+ * out just stops. This module looks at one ended turn of an agent whose role
+ * has a fallback chain (`FALLBACK_ROLES`) and no `bm.replacedBy` label, and
+ * reads one of two signals:
+ * - N1: the turn failed. The text is `outcome.error.message`.
+ * - N2: the turn completed without doing anything: no tool call, no
+ *   `BM-REPORT` or `BM-REVIEW` block in the agent's own messages (REQ-065 a:
+ *   a turn "without a BM-REPORT"; a Reviewer's verdict that woke a Worker is
+ *   not the Worker's report), a last assistant message of at most 500
+ *   characters, and either no output tokens or, when the provider reports no
+ *   tokens, a turn that was not started by one of the plugin's notices. The
+ *   text is that last message (proposal S3). The notice rule keeps a Manager's
+ *   one-line answer to a `BM-FALLBACK` from reading as a failure of its own.
+ * The text is then classified (`shared/fallback-patterns.ts`); L3 and L6 mean
+ * nothing is done, as before.
+ *
+ * Where each fact comes from:
+ * - The turn's items: the hook payload, cut at its last user message
+ *   (`sliceLastTurn`), as `format-check.ts` reads it. The refetch entries are
+ *   not filtered by `turnId` here because Paseo reuses turn ids inside one
+ *   agent (AGENTS.md), so an older turn with the same id could add its tool
+ *   calls.
+ * - Labels and output tokens: the agent snapshot of one `timeline.refetch`,
+ *   the same call the collector makes; `timestampsForTurn` turns it into
+ *   `usage`, so "0 output tokens" means exactly what a trace record says.
+ *
+ * Checks run cheapest first, so a turn with a tool call, or whose text does not
+ * classify as a fallback class, costs no daemon call. Nothing here records an
+ * incident or reads `role-fallback.json`: the caller hands the file's
+ * `patterns` in. Never throws: a failure costs one `[paseo-bm]` log line and
+ * the turn is not classified.
+ */
+import type { PluginLifecycleEvents } from "@getpaseo/plugin/server";
+import { FALLBACK_ROLES } from "../shared/fallback";
+import { compilePatterns, isFallbackClass, matchClass, type FallbackClass, type UserPatterns } from "../shared/fallback-patterns";
+import { roleOfAgent, roleOfProvider } from "./agent-role";
+import { parseReports, parseReviews } from "./bm-report";
+import { REFETCH_LIMIT, sliceLastTurn, timestampsForTurn, type CollectorPaseo } from "./collector";
+import { isPluginNotice } from "./notices";
+import type { Usage } from "../shared/contracts";
+
+type TurnEndedEvent = PluginLifecycleEvents["agent.turn_ended"];
+
+/** Label the plugin puts on an agent once a fallback agent took over from it (§4.4.7). */
+export const REPLACED_BY_LABEL = "bm.replacedBy";
+
+/** Longest last assistant message an N2 turn may end on. */
+export const MAX_QUIET_REPLY_CHARS = 500;
+
+/** A turn that ended on a provider-plan failure. */
+export interface FallbackSignal {
+  class: FallbackClass;
+  /** N1 (`failed`) or N2 (`completed`). */
+  signal: "failed" | "completed";
+  /** The text that was classified, trimmed; not cut, not redacted. */
+  message: string;
+}
+
+export interface FallbackDetectDeps {
+  /** Reads the agent's labels and usage; `PaseoApi` is structurally assignable. */
+  paseo: CollectorPaseo;
+  /** The `patterns` of `role-fallback.json`, read by the caller; absent means the defaults of every class. */
+  patterns?: UserPatterns | null;
+  log?: (message: string) => void;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isFallbackRole(role: unknown): boolean {
+  return (FALLBACK_ROLES as readonly unknown[]).includes(role);
+}
+
+function textItem(item: unknown): { type: string; text: string } | null {
+  if (item === null || typeof item !== "object") return null;
+  const { type, text } = item as { type?: unknown; text?: unknown };
+  if ((type !== "user_message" && type !== "assistant_message") || typeof text !== "string") return null;
+  return { type, text };
+}
+
+/** True when a message carries a `BM-REPORT` or `BM-REVIEW` block, read the way the collector reads them. */
+function hasBlock(text: string): boolean {
+  const context = { agentId: "", at: "" };
+  return parseReports(text, context).length > 0 || parseReviews(text, context).length > 0;
+}
+
+/**
+ * The last assistant message of a turn that did nothing else (N2 conditions
+ * 1 to 3), trimmed, or null: the turn has a tool call, an assistant message
+ * with a block, no assistant message, or a last one that is empty or longer
+ * than `MAX_QUIET_REPLY_CHARS`. A block in a message the agent RECEIVED does
+ * not count: a Worker woken by its Reviewer's `BM-REVIEW` can still hit its limit.
+ */
+export function quietReply(items: readonly unknown[]): string | null {
+  let last: string | null = null;
+  for (const item of items) {
+    if ((item as { type?: unknown } | null)?.type === "tool_call") return null;
+    const message = textItem(item);
+    if (message === null || message.type !== "assistant_message") continue;
+    if (hasBlock(message.text)) return null;
+    last = message.text;
+  }
+  const reply = last?.trim() ?? "";
+  return reply !== "" && reply.length <= MAX_QUIET_REPLY_CHARS ? reply : null;
+}
+
+/**
+ * N2 condition 4: the turn produced no output tokens, or, when the provider
+ * reports none (`usage` null), the message that started it is not one of the
+ * plugin's notices. A turn with no user message counts as not started by one.
+ */
+export function quietTokens(usage: Usage | null, items: readonly unknown[]): boolean {
+  if (usage !== null) return usage.outputTokens === 0;
+  const first = items.length > 0 ? textItem(items[0]) : null;
+  return !isPluginNotice(first?.type === "user_message" ? first.text : null);
+}
+
+/**
+ * The agent's labels and usage from one `timeline.refetch`. The payload is
+ * handed to the collector's own reader so the usage is read exactly as a trace
+ * record's. Throws when the call fails or the payload carries no snapshot.
+ */
+async function readAgent(
+  paseo: CollectorPaseo,
+  agentId: string,
+  turnId: string | null,
+): Promise<{ labels: Record<string, unknown>; usage: Usage | null }> {
+  const payload = await paseo.agents.ref(agentId).timeline.refetch({ direction: "tail", limit: REFETCH_LIMIT });
+  const snapshot = (payload as { agent?: unknown } | null)?.agent;
+  if (snapshot === null || typeof snapshot !== "object") throw new Error("the timeline refetch returned no agent snapshot");
+  const replay: CollectorPaseo = { agents: { ref: () => ({ timeline: { refetch: async () => payload } }) } };
+  const { usage } = await timestampsForTurn({ location: null, paseo: replay }, agentId, turnId);
+  const labels = (snapshot as { labels?: unknown }).labels;
+  return { labels: labels !== null && typeof labels === "object" ? (labels as Record<string, unknown>) : {}, usage };
+}
+
+/**
+ * Classifies one ended turn. Returns the class, the signal and the text when
+ * the turn ended on an L1, L2, L4 or L5 failure; null otherwise, including
+ * for a canceled turn, an agent outside `FALLBACK_ROLES`, an agent already
+ * replaced, and any failure (logged once).
+ *
+ * The event carries no labels, so the provider filters first: an agent whose
+ * provider is not a paseo-bm alias of a fallback role is never fetched. The
+ * snapshot's labels then decide as `roleOfAgent` does, the `bm.role` label
+ * winning over the provider.
+ */
+export async function classifyTurn(event: TurnEndedEvent, deps: FallbackDetectDeps): Promise<FallbackSignal | null> {
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  let agentId = "(unknown)";
+  try {
+    const agent = event.agent;
+    agentId = typeof agent?.id === "string" ? agent.id : agentId;
+    const outcome = event.outcome;
+    if (outcome?.kind !== "failed" && outcome?.kind !== "completed") return null;
+    if (!isFallbackRole(roleOfProvider(agent.provider))) return null;
+
+    const items = sliceLastTurn(Array.isArray(event.timeline) ? event.timeline : []);
+    const message =
+      outcome.kind === "failed"
+        ? typeof outcome.error?.message === "string"
+          ? outcome.error.message.trim()
+          : ""
+        : quietReply(items);
+    if (message === null || message === "") return null;
+    const found = matchClass(message, compilePatterns(deps.patterns, log));
+    if (!isFallbackClass(found)) return null;
+
+    const { labels, usage } = await readAgent(deps.paseo, agent.id, event.turnId);
+    if (!isFallbackRole(roleOfAgent({ provider: agent.provider, labels })?.role)) return null;
+    if (Object.prototype.hasOwnProperty.call(labels, REPLACED_BY_LABEL)) return null;
+    if (outcome.kind === "completed" && !quietTokens(usage, items)) return null;
+    return { class: found, signal: outcome.kind, message };
+  } catch (error) {
+    log(`[paseo-bm] fallback detection skipped a turn of agent ${agentId}: ${describeError(error)}`);
+    return null;
+  }
+}

package/server/fallback-handover.ts

@@ -0,0 +1,365 @@
+/**
+ * The handovers a replacement agent starts from (delta 20260921 §4.4.8,
+ * §4.5.2, REQ-065 d, REQ-066 c), built in code from stored data — never
+ * summarised by a model.
+ *
+ * Worker (`workerHandover`):
+ *
+ * | Field | Source |
+ * |---|---|
+ * | `requestId` | the replaced Worker's `bm.requestId` label, recorded on the incident |
+ * | report fields | the LATEST `BM-REPORT` of that request in the workspace trace store |
+ * | `reviewCalls` | the request's reconstructed trace, against its tier's budget; a replacement Reviewer's first message is not counted (§4.5.1) |
+ * | original request | the first `user_message` of the replaced Worker's timeline |
+ *
+ * Manager (`managerHandover`):
+ *
+ * | Field | Source |
+ * |---|---|
+ * | `workers` | live, non-replaced Workers of the workspace (`bmAgentsOf`, `liveWorkersOf`); provider and model from each one's snapshot; last report as for the Worker |
+ * | `openQuestions` | `waitingOf` (the pill's rule) on the old Manager's timeline |
+ * | `openIncidents` | the workspace's other `pending` or `waiting` incidents |
+ * | user's messages | the three newest `user_message` items WITH `clientMessageId` (the user's own words) in the old Manager's timeline |
+ *
+ * Each source is raced against the budget (5 s by default): a missing part
+ * reads `unknown` (`unavailable` for the Worker's request text) and never
+ * blocks the switch. Every quoted user text is masked like every trace record
+ * (REQ-048b).
+ */
+import { peersOfWorkspace } from "./chat-peers";
+import { WAITING_TIMELINE_LIMIT, WAITING_TIMELINE_PAGES, waitingOf, type WaitingEntry } from "./chat-waiting";
+import { redactText } from "./collector";
+import { agentFactsOf, bmAgentsOf, reviewerReplacementIds, reviewerReplacementsFor, type DashboardPaseo } from "./dashboard-rpc";
+import { replacementsOf } from "./fallback-state";
+import { LIVE_MAX_PAGES, LIVE_PAGE_LIMIT, readTimelinePages, type LiveTimelinePaseo } from "./live-timeline";
+import { isPluginNotice } from "./notices";
+import { providerId } from "./provider-id";
+import { REVIEW_BUDGET } from "./review-budget";
+import { asRecord, nonEmpty } from "./role-choices";
+import { TRUNCATION_MARKER, readRecords, type TraceStoreLocation } from "./trace-store";
+import { reconstructTraces } from "./traces";
+import { FALLBACK_CLASS_LABELS } from "../shared/bm-fallback";
+import { parseQuestions } from "../shared/bm-questions";
+import type { ChatPeer, FallbackIncident, ParsedReport, TraceRecord, WaitingWorker } from "../shared/contracts";
+
+/** First line of the handover. */
+export const HANDOVER_MARKER = "BM-HANDOVER";
+
+/** Budget of the whole handover (§4.4.8). */
+export const HANDOVER_BUDGET_MS = 5000;
+
+/** Longest failure message quoted in the `reason` line. */
+const REASON_MESSAGE_CHARS = 300;
+
+/** Longest `blockers` text of a Manager handover's Worker line. */
+const BLOCKERS_CHARS = 300;
+
+/** The user's newest messages a Manager handover quotes, and the longest one. */
+const QUOTED_MESSAGES = 3;
+const QUOTED_MESSAGE_CHARS = 1000;
+
+/** Incidents a new Manager inherits: still to be decided, or waiting for a reset. */
+const OPEN_INCIDENT_STATUSES: ReadonlySet<FallbackIncident["status"]> = new Set(["pending", "waiting"]);
+
+/** Last paragraph of the Manager handover (§4.5.2). */
+const MANAGER_CLOSING =
+  "You are the Beads Manager of this workspace from now on. Every Worker listed was told your id. Tell the user in one line that you took over, then carry on.";
+
+export interface HandoverDeps {
+  /** Agent listing and timelines; `PaseoApi` is structurally assignable. */
+  paseo: unknown;
+  /** The workspace trace store; `null` when tracing is off (the report fields read `unknown`). */
+  location: TraceStoreLocation | null;
+  log?: (message: string) => void;
+  budgetMs?: number;
+  /**
+   * Every recorded incident (`readIncidents`). The Worker handover counts
+   * `reviewCalls` without the first message of each Reviewer that replaced a
+   * stopped one (§4.5.1); read from the install home when absent, none when `null`.
+   */
+  incidents?: readonly FallbackIncident[] | null;
+}
+
+/** `work()` within `budget` ms, or `null` on timeout or failure. Never throws. */
+async function within<T>(budget: number, work: () => Promise<T> | T): Promise<T | null> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(work),
+      new Promise<null>((resolve) => {
+        timer = setTimeout(() => resolve(null), budget);
+        timer.unref?.();
+      }),
+    ]);
+  } catch {
+    return null;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/** The request's latest `BM-REPORT` in the trace store, or null. */
+function latestReport(records: readonly TraceRecord[], requestId: string): ParsedReport | null {
+  let latest: ParsedReport | null = null;
+  for (const record of records) {
+    for (const report of record.reports) {
+      if (report.requestId !== requestId) continue;
+      if (latest === null || report.at >= latest.at) latest = report;
+    }
+  }
+  return latest;
+}
+
+/** The first `user_message` of an agent's timeline (bounded walk back to its start), masked; null when none. */
+async function firstUserMessage(paseo: unknown, agentId: string): Promise<string | null> {
+  let first: string | null = null;
+  await readTimelinePages(paseo as LiveTimelinePaseo, agentId, { pages: LIVE_MAX_PAGES, limit: LIVE_PAGE_LIMIT }, (entries) => {
+    // Pages come newest first, each oldest first: every older page's first message replaces the last one found.
+    const found = entries
+      .map((entry) => entry.item as { type?: unknown; text?: unknown } | undefined)
+      .find((item) => item?.type === "user_message" && typeof item.text === "string" && item.text.trim() !== "");
+    if (found !== undefined) first = found.text as string;
+  });
+  return first === null ? null : redactText(first);
+}
+
+const list = (values: readonly string[] | undefined): string => (values === undefined ? "unknown" : values.length === 0 ? "none" : values.join(", "));
+
+/** `text` on one line, at most `max` characters. */
+const oneLine = (text: string, max: number): string => text.replace(/\s+/g, " ").trim().slice(0, max);
+
+/** The `reason` line: the failure class and the provider's own words. */
+const reasonLine = (incident: FallbackIncident): string =>
+  `reason: ${FALLBACK_CLASS_LABELS[incident.class]} — "${oneLine(incident.message, REASON_MESSAGE_CHARS)}"`;
+
+/**
+ * The `BM-HANDOVER` block that starts the replacement of `incident`'s Worker.
+ * Never throws: every part it cannot get in time reads `unknown`.
+ */
+export async function workerHandover(incident: FallbackIncident, deps: HandoverDeps): Promise<string> {
+  const budget = deps.budgetMs ?? HANDOVER_BUDGET_MS;
+  const requestId = incident.requestId;
+  const records =
+    deps.location === null ? null : await within(budget, () => readRecords(deps.location!, incident.workspaceId).records);
+  const [report, review, original] = await Promise.all([
+    within(budget, () => (records === null || requestId === null ? null : latestReport(records, requestId))),
+    within(budget, async () => {
+      if (records === null || requestId === null) return null;
+      // The same count as the BM-BUDGET check (delta 20260921 §4.5.1).
+      const [facts, replacementIds] = await Promise.all([
+        agentFactsOf(deps.paseo as DashboardPaseo, incident.workspaceId),
+        deps.incidents === undefined ? reviewerReplacementsFor(deps.paseo) : reviewerReplacementIds(deps.incidents ?? []),
+      ]);
+      return reconstructTraces({ records, agents: [...facts.values()], replacementIds }).find((trace) => trace.requestId === requestId) ?? null;
+    }),
+    within(budget, () => firstUserMessage(deps.paseo, incident.agentId)),
+  ]);
+
+  const tier = report?.tier ?? review?.tier ?? null;
+  const calls = review?.reviewCalls ?? null;
+  const reviewCalls = calls === null ? "unknown" : tier === null ? `${calls} of an unknown budget` : `${calls} of ${REVIEW_BUDGET[tier]}`;
+
+  return [
+    HANDOVER_MARKER,
+    "role: worker",
+    `requestId: ${requestId ?? "unknown"}`,
+    `managerAgentId: ${incident.managerId ?? "none"}`,
+    `replaces: ${incident.agentId}`,
+    reasonLine(incident),
+    `lastReport: ${report === null ? "none" : `${report.phase ?? "unknown"} at ${report.at}`}`,
+    `tier: ${tier ?? "unknown"}`,
+    `filesChanged: ${list(report?.filesChanged)}`,
+    `beadsCreated: ${list(report?.beadsCreated)}`,
+    `beadsUpdated: ${list(report?.beadsUpdated)}`,
+    `beadsClosed: ${list(report?.beadsClosed)}`,
+    `beadsReady: ${list(report?.beadsReady)}`,
+    `reviewFindingsOpen: ${report === null ? "unknown" : (report.reviewFindingsOpen ?? "none")}`,
+    `reviewCalls: ${reviewCalls}`,
+    `skillsUsed: ${list(report?.skillsUsed)}`,
+    "",
+    "Original request (verbatim, the first message the replaced Worker received):",
+    original ?? "unavailable",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Manager (§4.5.2, REQ-066 c).
+// ---------------------------------------------------------------------------
+
+export interface ManagerHandoverDeps extends HandoverDeps {
+  /**
+   * Every recorded incident (`readIncidents`): the workspace's open ones, and
+   * the agents a `switched` one replaced. `null` when the file cannot be read
+   * (`openIncidents: unknown`).
+   */
+  incidents: readonly FallbackIncident[] | null;
+  /** Whose secret values are masked in the quoted messages; `process.env` by default. */
+  env?: NodeJS.ProcessEnv;
+}
+
+/** The SDK slice that reads one agent's snapshot; `PaseoApi` is structurally assignable. */
+interface SnapshotPaseo {
+  agents: { ref?(agentId: string): { refresh?(): Promise<{ agent?: unknown } | null> } };
+}
+
+/** What a Manager handover reads from the old Manager's timeline, filled page by page. */
+interface ManagerTimeline {
+  /** Pages read so far. */
+  pages: number;
+  /** The pill's window (`WAITING_TIMELINE_PAGES`), newest first, as `waitingOf` wants it. */
+  recent: WaitingEntry[];
+  /** The user's own messages, newest first, masked and cut; at most `QUOTED_MESSAGES`. */
+  typed: string[];
+}
+
+/**
+ * The Workers a Manager handover lists — and so the ones the switch tells the
+ * new Manager's id (§4.5.2 step 5): live (neither archived nor closed) and not
+ * replaced by a fallback Worker.
+ */
+export function liveWorkersOf<P extends Pick<ChatPeer, "role" | "status" | "archived" | "replaced">>(peers: readonly P[]): P[] {
+  return peers.filter((peer) => peer.role === "worker" && !peer.archived && peer.status !== "closed" && !peer.replaced);
+}
+
+/**
+ * The text of a message the user typed in the app: a `user_message` with
+ * `clientMessageId` (AGENTS.md), and neither a plugin notice nor a handover.
+ */
+function typedText(item: unknown): string | null {
+  const message = item as { type?: unknown; text?: unknown; clientMessageId?: unknown } | null | undefined;
+  if (message?.type !== "user_message" || typeof message.clientMessageId !== "string") return null;
+  const text = nonEmpty(message.text);
+  return text === null || isPluginNotice(text) || text.startsWith(HANDOVER_MARKER) ? null : text;
+}
+
+/** A quoted user message: masked first, so a secret across the cut is masked whole, then cut. */
+function quoted(text: string, env: NodeJS.ProcessEnv): string {
+  const masked = redactText(text, env);
+  if (masked.length <= QUOTED_MESSAGE_CHARS) return masked;
+  return `${masked.slice(0, QUOTED_MESSAGE_CHARS - TRUNCATION_MARKER.length)}${TRUNCATION_MARKER}`;
+}
+
+/**
+ * Reads the old Manager's timeline back to its start (bounded) into `into`:
+ * the pill's window and the user's newest messages. Filled as pages arrive,
+ * so what was read before the budget ran out still counts.
+ */
+async function readManagerTimeline(paseo: unknown, managerId: string, into: ManagerTimeline, env: NodeJS.ProcessEnv): Promise<true> {
+  await readTimelinePages(paseo as LiveTimelinePaseo, managerId, { pages: LIVE_MAX_PAGES, limit: WAITING_TIMELINE_LIMIT }, (entries) => {
+    // Pages come newest first, each oldest first.
+    const newestFirst = [...entries].reverse();
+    if (into.pages < WAITING_TIMELINE_PAGES) into.recent.push(...newestFirst);
+    into.pages += 1;
+    for (const entry of newestFirst) {
+      if (into.typed.length >= QUOTED_MESSAGES) break;
+      const text = typedText(entry.item);
+      if (text !== null) into.typed.push(quoted(text, env));
+    }
+  });
+  return true;
+}
+
+/** An agent's current snapshot, or null. */
+async function snapshotOf(paseo: unknown, agentId: string): Promise<Record<string, unknown> | null> {
+  const ref = (paseo as SnapshotPaseo).agents.ref?.(agentId);
+  return asRecord((await ref?.refresh?.())?.agent);
+}
+
+/** One `workers:` line; every part it cannot know reads `unknown`. */
+function workerLine(worker: ChatPeer, records: readonly TraceRecord[] | null, snapshot: Record<string, unknown> | null): string {
+  const provider = providerId(nonEmpty(snapshot?.["provider"]));
+  // The model the agent runs: `runtimeInfo.model` first (AGENTS.md), else the configured one.
+  const model = nonEmpty(asRecord(snapshot?.["runtimeInfo"])?.["model"]) ?? nonEmpty(snapshot?.["model"]);
+  const runsOn = provider === null && model === null ? "unknown" : `${provider ?? "unknown"}/${model ?? "unknown"}`;
+  const report = records === null || worker.requestId === null ? undefined : latestReport(records, worker.requestId);
+  const last = report === undefined ? "unknown" : report === null ? "none" : `${report.phase ?? "unknown"} at ${report.at}`;
+  const blockers = report === undefined ? "unknown" : report === null || report.blockers === null ? "none" : oneLine(report.blockers, BLOCKERS_CHARS);
+  return `- ${worker.id} · requestId ${worker.requestId ?? "unknown"} · ${runsOn} · ${worker.status} · last report: ${last} · blockers: ${blockers}`;
+}
+
+/** `workerId: Q1, Q2; …` for the Workers waiting on the user, or `none`. */
+function questionsOf(waiting: readonly WaitingWorker[]): string {
+  const parts = waiting.map((entry) => `${entry.workerId}: ${(parseQuestions(entry.text)?.questions ?? []).map((question) => question.id).join(", ")}`);
+  return parts.length === 0 ? "none" : parts.join("; ");
+}
+
+/** The workspace's other open incidents, oldest first, or `none`; `unknown` without the incidents file. */
+function openIncidentsOf(incident: FallbackIncident, incidents: readonly FallbackIncident[] | null): string {
+  if (incidents === null) return "unknown";
+  const open = incidents.filter(
+    (entry) => entry.id !== incident.id && entry.workspaceId === incident.workspaceId && OPEN_INCIDENT_STATUSES.has(entry.status),
+  );
+  return open.length === 0 ? "none" : open.map((entry) => entry.id).join(", ");
+}
+
+/**
+ * The `BM-HANDOVER` block that starts the replacement of `incident`'s Manager.
+ * One budget for the whole block: the old Manager's timeline is read beside
+ * the agent list and the trace store, then the Workers' snapshots in what is
+ * left — so a slow timeline never starves the Worker lines. Never throws:
+ * every part it cannot get in time reads `unknown`, with one log line naming
+ * what was late.
+ */
+export async function managerHandover(incident: FallbackIncident, deps: ManagerHandoverDeps): Promise<string> {
+  const budget = deps.budgetMs ?? HANDOVER_BUDGET_MS;
+  const deadline = Date.now() + budget;
+  const left = (): number => Math.max(0, deadline - Date.now());
+  const log = deps.log ?? ((message: string) => console.warn(message));
+  const { workspaceId, agentId: managerId } = incident;
+  const timeline: ManagerTimeline = { pages: 0, recent: [], typed: [] };
+
+  const walking = within(budget, () => readManagerTimeline(deps.paseo, managerId, timeline, deps.env ?? process.env));
+  const [records, all] = await Promise.all([
+    deps.location === null ? null : within(left(), () => readRecords(deps.location!, workspaceId).records),
+    within(left(), () => bmAgentsOf(deps.paseo as DashboardPaseo)),
+  ]);
+  // An empty list is a failed one: the old Manager itself is always on it.
+  const agents = all === null || all.length === 0 ? null : all;
+  const peers =
+    agents === null ? null : await within(left(), () => peersOfWorkspace(agents, workspaceId, async () => records ?? [], replacementsOf(deps.incidents ?? [])));
+  const workers = peers === null ? null : liveWorkersOf(peers);
+  const snapshots = workers === null ? [] : await Promise.all(workers.map((worker) => within(left(), () => snapshotOf(deps.paseo, worker.id))));
+  const walked = await walking;
+
+  // The pill's rule, on the pill's window of the old Manager's timeline.
+  const windowRead = timeline.pages > 0 && (walked !== null || timeline.pages >= WAITING_TIMELINE_PAGES);
+  const waiting =
+    peers === null || !windowRead
+      ? null
+      : await within(left(), () =>
+          waitingOf(
+            { id: managerId, workspaceId },
+            timeline.recent,
+            peers.filter((peer) => peer.role === "worker").map((peer) => ({ ...peer, workspaceId })),
+          ),
+        );
+  const typed = [...timeline.typed].reverse();
+  const messages = typed.length > 0 ? typed.map((text, index) => `${index + 1}. ${text}`) : [timeline.pages > 0 && walked !== null ? "none" : "unknown"];
+
+  const late = [
+    ...(deps.location !== null && records === null ? ["the trace store"] : []),
+    ...(agents === null || peers === null ? ["the agent list"] : []),
+    ...(timeline.pages === 0 ? [`the timeline of Manager ${managerId}`] : []),
+  ];
+  if (late.length > 0) log(`[paseo-bm] the handover of incident ${incident.id} could not read ${late.join(", ")} within ${budget} ms; those parts read unknown.`);
+
+  return [
+    HANDOVER_MARKER,
+    "role: manager",
+    `workspaceId: ${workspaceId}`,
+    `replaces: ${managerId}`,
+    reasonLine(incident),
+    ...(workers === null
+      ? ["workers: unknown"]
+      : workers.length === 0
+        ? ["workers: none"]
+        : ["workers:", ...workers.map((worker, index) => workerLine(worker, records, snapshots[index] ?? null))]),
+    `openQuestions: ${waiting === null ? "unknown" : questionsOf(waiting)}`,
+    `openIncidents: ${openIncidentsOf(incident, deps.incidents)}`,
+    "",
+    "The user's last messages to the Manager you replace (oldest first, verbatim):",
+    ...messages,
+    "",
+    MANAGER_CLOSING,
+  ].join("\n");
+}